Compare commits

...
36 Commits
Author SHA1 Message Date
mesh-tools a6d22f10fb Merge pull request 'Design 47 H2: the kept call paced, take once, page by cursor, settings, class and caps, check-needs' (#209) from feat/47-H2 into main 2026-11-22 03:50:58 +00:00
jschoubben 087e41497e The tests' seat list takes again node-engine, whose have's pipeline description moved
seatlisttest takes again node-engine from mesh-contracts feat/47-H2 ba5a2538,
where only the have's pipeline description changed (a want's run is compared
with the have's run only when the want's branch is the same), no form change.
It is a bootstrapped seat, so the bootstrap copy and its captured contracts
copy are replaced too (ADR 0635 §3), and CAPTURED names the commit. Every
other seat and both parts still equal the group's heads (mesh-contracts
feat/47-H2 ba5a2538, mesh-delivery feat/47-H2 abfe37e6, mesh-networking
feat/47-H2 18e564c0).

Builds: design 47 H2, H-A-452, ADR 0635 §3
2026-11-22 03:15:14 +01:00
jschoubben 78fd003263 The tests' seat list takes again five definitions the group's heads moved, two of them bootstrapped
seatlisttest takes again mesh-builds (its verb publish-queue), mesh-delivery,
mesh-wants (keep-now), node-engine (form 4: the have's run keeps its pipeline,
the composition answer gains drift) and node-packet-filter from the group's
current heads (mesh-contracts feat/47-H2 8f2bed18, mesh-delivery feat/47-H2
abfe37e6, mesh-networking feat/47-H2 18e564c0), so a test judges a manifest
against the seats the running validator judges it against; every other seat
and both parts already equal those heads. The two bootstrapped seats among
them (mesh-delivery, node-engine) are replaced in the bootstrap and its
captured contracts copy too (ADR 0635 §3), and CAPTURED names the commits.

Builds: design 47 H2, H-A-452
2026-11-22 02:58:54 +01:00
jschoubben a323a3fd54 The tests' seat list holds the group's definitions: mesh-recovery and four more seats, eleven taken again
seatlisttest gains mesh-builds, mesh-delivery-view, mesh-grants,
mesh-pipeline-runner and mesh-recovery, which the live list (revision 473)
holds, and takes again the eleven definitions and two parts the group's heads
change (mesh-contracts feat/47-H2 e6ed560e, mesh-delivery feat/47-H2 80ff1afa,
mesh-catalog's form 5 from feat/47-H2-i 5e943280), so a test judges a manifest
against the seats the running validator judges it against. The three
bootstrapped seats among them (mesh-catalog, mesh-delivery, node-engine) are
replaced in the bootstrap and its captured contracts copy too (ADR 0635 §3,
ADR 0636 §7); the service manager's tests take its kernel-log verb, and the
grants module's name, now also a seat's, joins the kept names.

Builds: design 47 H2, H-A-452
2026-11-22 02:29:29 +01:00
jschoubben f90189353c Fold H2's new tests into existing ones: go/ at 327 unit tests (from 331), TypeScript at 48 (from 49)
The eight Go test functions H2 added become subtests of existing tests
(catalogue's state test, the bundle's state test, the views test, the process
state test, the testbus bus test, the seal byte-for-byte test), and four more
are folded beside them (two seal, two process watch); the two TypeScript seal
tests become one, and two more TypeScript tests are folded into their
neighbours. No assertion is lost.

Builds: design 47 H2 §819
2026-11-22 02:25:44 +01:00
jschoubben 7d7a89411c M1 check-needs: a manifest names at its top level the seats a package outside every artifact's from needs
A package no artifact's from holds (the forge module's seatgit whole test) has no artifact to carry its
check-needs, so the module says it once at its level, in the artifact's form (H-A-453 (2)).

Builds: design 47 H2 §800, H-A-453 (2)
2026-11-22 02:24:49 +01:00
jschoubben 4e338436da Kept-call pace read once and atomically: no data race with the kept calls reading it
ReadPace wrote the pace at every Connect and Serve while kept calls on other
goroutines read it. The pace is now held atomically and read once at the
start: a later read of the same pace changes nothing, one of another pace is
refused naming both. KeptPace becomes a function.

Builds: design 47 H2 §782, §775
2026-11-22 02:21:53 +01:00
jschoubben 03e2aca59f S4 page by cursor: a page hands a kept delete as an entry marked deleted with no value
A reader following pages removes the key, so a deleted key never comes back
alive from a bucket with history.

Builds: design 47 H2 §779, H-A-451 (1)
2026-11-22 02:19:27 +01:00
jschoubben ed281663fd S16 addendum: a waiting ask says when it waits again after a nak
Builds: design 47 H2 §777, H-A-410 and its addendum
2026-11-22 01:00:24 +01:00
jschoubben d6cdf3b8f5 S15 TypeScript seals: seal, open and sealAnonymous beside go/seal
The forge module's minting processes are TypeScript and the vault's two steps need ADR 0206's
sealed box and the NaCl anonymous box its intake opens; both now live once in mesh-sdk, proven
byte for byte against the Go package's bytes (tweetnacl 1.0.3 and blakejs 1.2.1 pinned).

Builds: design 47 H2 §808, §822, H-A-407 and its addendum
2026-11-22 00:59:54 +01:00
jschoubben 3ad8ccbc06 S16 QueueWaiting: a holder reads its own seat queue's waiting asks through the runtime
A holder's asks tool answers what waits on its seat's queue; the queue is its own store, so
the read is the owner's, one shared form asked of the tool runner as mesh/queue.waiting.

Builds: design 47 H2 §777, H-A-410
2026-11-22 00:56:35 +01:00
jschoubben 3f8f35a87a S14 kept chunked call: CallChunksKept and CallFileKept pace the ask and carry its id on every chunk
The assigner's compose-candidate ask is chunked, and the one-shot CallFile ended at the
first no responders; the kept call's form now makes the chunked call too.

Builds: design 47 H2 §775, H-A-405 (1), H-A-351
2026-11-22 00:55:25 +01:00
jschoubben c99295c21d The starved setup's line lives in the root package
stdio.SetupStarved holds "mesh: setup starved:" so the delivery SDK reads
it without importing testbus; testbus.SetupStarved names it.

Builds: design 47 H2 §800; H-A-368, H-A-399
2026-11-22 00:52:02 +01:00
jschoubben 5dd0d66acb S10 check-needs names the seats a package's tests need the node to hold
check-needs is a list of seat names (node-build-node), as the marker
file named them, not the value node-modules.

Builds: design 47 H2 §800; H-A-350 DMC-6, H-A-399 (3)
2026-11-22 00:44:18 +01:00
jschoubben e54151336e S13 bootstrap copy of git: take the git seat as D5 defines it
The bootstrapped definition, its test copy and the captured contract file
are replaced by mesh-delivery's seats/git/seat.json at D5 (tags name their
commits, a holder says away), byte for byte.

Builds: design 47 H2 §796, §776; H-A-350 DMC-3
2026-11-22 00:22:57 +01:00
jschoubben 98ed28c1d1 S12 class: a manifest says whether its module is core or a leaf
The gate reads a mover's class from its catalog entry; a module that
names none is a leaf.

Builds: design 47 H2 §810, §814; H-A-394 (1)
2026-11-22 00:21:38 +01:00
jschoubben 7e538e3eae S12 caps in the catalog: a manifest says each kept store that names no cap
The manifest validator refuses a delivery module's state, log or objects
entry with no cap; the catalog reads them from the old sections and the
requires entries alike, so the validator judges one list.

Builds: design 47 H2 §814, §812
2026-11-22 00:20:57 +01:00
jschoubben 134b111e3f Raise the declaration's Version to 2 for drain-bound; manifests state the Version read and written
Version is the declaration's form: drain-bound raises it by one, and a
node-engine refuses only a higher one, so it still takes what a composer
of version 1 writes. A manifest says declaration-reads (the node-engine's)
and declaration-writes (the composer's), so the delivery plan can order
the writer of a Version after every engine that reads it.

Builds: design 47 H2 §813 (12), H-A-388 (2), H-A-358
2026-11-22 00:19:52 +01:00
jschoubben 484e2bba3c S11 prune helper and tools: a kept store is pruned toward its cap at its own writes
A process judges a running sum of what its writes put against the figures
read at the bind and after each prune; a bundle judges the fill the
runtime's put answer carries. Past prune-mark (70 %) the oldest keys by
revision go down to prune-target (50 %), in one journal line; a key kept
under _keep/<key> stays, and no reader counts the keep. The generic tools
<module>_state_prune_now and <module>_state_keep act through the hand-act log.

Builds: design 47 H2 §812, H-A-380, H-A-386
2026-11-22 00:17:36 +01:00
jschoubben fe052c135e Read a state's max-mib in the manifest-reads baseline
Every running node-engine reads a state's max-mib (it writes every
module's bucket cap from it), so the baseline a node-engine that states
nothing is read as stating carries it.

Builds: design 47 H2 §812, §820; H-A-383
2026-11-22 00:06:15 +01:00
jschoubben 450ea7eddc S10 check-needs: a Go artifact declares what its tests need in its manifest
catalogue.Artifact gains check-needs (node-modules), the field that
replaces the marker file in a package's directory; its readers read it
from the manifest.

Builds: design 47 H2 §800; H-A-350 DMC-6
2026-11-22 00:04:53 +01:00
jschoubben eee02a20a9 S7 safe for concurrent use: hold the bus wrappers to it under the race detector
Many goroutines' gets, puts, pages, keys and watches through one bundle's
runtime channel, one process connection's state and one process reader's
pictures run under the race detector; no unguarded call was found, so the
tests hold the wrappers to it.

Builds: design 47 H2 §782; H-A-349 DQ-3
2026-11-22 00:03:19 +01:00
jschoubben e9481928f5 KeptPace from settings: a module's declared pace paces its kept calls
busretry.ReadPace sets the kept-call pace from kept-call-pace-first and
kept-call-pace-max through the one settings reader; process.Connect and a
bundle's Serve read it at their start and refuse a value that is no
duration.

Builds: design 47 H2 §775, §781; H-A-370
2026-11-21 23:59:04 +01:00
jschoubben 139626daab S9 setup bound: a starved setup on the bus says so in one line
A test's setup waits on the bus for half of its level's bound
(MESH_TEST_LEVEL_BOUND), 30 s when unset, and fails with the line
"mesh: setup starved:" a build module reads to run the level again.

Builds: design 47 H2 §800; H-A-368
2026-11-21 23:57:12 +01:00
jschoubben 92cb6a8d6d S4 page by cursor: a state page continues from an opaque cursor in sequence order
The runtime's mesh/state.page takes the cursor the page before answered as
next, so a state is read once however many pages it takes; a key written
again since an earlier page comes marked seen-again.

Builds: design 47 H2 §779
2026-11-21 23:56:07 +01:00
jschoubben 6d290eb46b S6 settings: read a setting by its key in a process and a bundle
The node-engine composes each config value as MESH_CONFIG_<KEY>, in a
process's environment and the module's tool-runner slice alike;
stdio.Setting and SettingDuration read it, the one reader both sides use.

Builds: design 47 H2 §781; H-A-350 DMC-13, H-A-370
2026-11-21 23:23:15 +01:00
jschoubben ab05031e9a Purge a deleted object's leftovers through the runtime's delete
The runtime's objects delete already purges an object's chunks, and purges
them again when asked again: Purge and purgeObject ask it, and no act of
their own is added.

Builds: design 47 H2 §812; H-A-366 (correction)
2026-11-21 23:22:38 +01:00
jschoubben 75287d8ce5 Let a bundle purge a deleted object's leftovers through the runtime
The runtime's objects act purge removes a deleted object's chunks:
busstate.Objects.Purge and TypeScript purgeObject, so the registry's
program opens no connection of its own for it.

Builds: design 47 H2 §812; H-A-366
2026-11-21 23:20:52 +01:00
jschoubben 0c27544582 Let a holder take asks once over a store bound on its own link
process.StateOver gives a State over a key-value store the caller bound
itself, so the node-engine, which serves its seat over its own link, keeps
the asks it took in its own taken state.

Builds: design 47 H2 §775; H-A-364
2026-11-21 23:19:11 +01:00
jschoubben 6852228000 Derive a seat's work queue and its worker from the seat definition
An accepted kind names its work queue's settings (max-age,
duplicates-window, ack-wait, in-progress, max-msgs, max-ack-pending,
max-deliveries); buscompose.SeatQueue derives the seat's work-queue stream
and its one shared worker from them, once, for the grants part to take.

Builds: design 47 H2 §777; H-A-350 DMC-1, H-A-362, H-A-340 (1)
2026-11-21 23:18:34 +01:00
jschoubben 1f2b1cd46b Carry a seat definition's form and a part's form
A definition and a part gain form, raised at every field their messages
add or remove; absent reads 1 and below 1 is refused, so the generator can
hold a changed definition to a raised form.

Builds: design 47 H2 §780; H-A-352 (1)
2026-11-21 23:14:28 +01:00
jschoubben 25b3030a93 S2 take once in a bundle too, Go and TypeScript
A bundle holder takes an ask once through the runtime's create with the
ask's bound as the key's time to live: stdio.KeptState.TakeOnce and
TypeScript takeOnce; stdio.TakenState and TakenKey are the one name, which
process refers to.

Builds: design 47 H2 §775, §820; H-A-359
2026-11-21 23:12:58 +01:00
jschoubben 423de0e8a2 S3 away: read a holder's answer of the kind away as a transport fault
A holder answers error-kind away, with part and words, when a part it
depends on is away; the kept call reads it from the answer and calls again
at the pace. Go: busretry.ErrorKindAway, AwayAnswer, AwayIn, Away;
TypeScript: ERROR_KIND_AWAY, awayAnswer, awayIn.

Builds: design 47 H2 §776, §775; H-A-349 DQ-15, H-A-350 DMC-2, H-A-354
2026-11-21 23:10:27 +01:00
jschoubben d40fa0b3a0 Carry a process's drain bound in the declaration
A process that stays up may name drain-bound (seconds): the node-engine
writes its unit's stop from it, so the tool runner finishes its calls in
flight before it exits. Absent is none; a step or a scheduled run is
refused one.

Builds: design 47 H2 §813 (12); H-A-358, H-A-353
2026-11-21 23:08:38 +01:00
jschoubben f5dc3b6bd1 S2 take once: keep the ids a holder took in its state taken
A holder of a kept call takes an ask once by its id: TakeOnce creates
<seat>.<ask> in the state taken with the ask's bound as its time to live,
and a second ask of the same id within it answers false.

Builds: design 47 H2 §775, §820; H-A-338 (6), H-A-339 (4)
2026-11-21 23:08:38 +01:00
jschoubben 14c2532b0c S1 kept call paced: carry the ask id, pace at the settings' defaults with jitter, stop at the caller's bound
The kept call is made again on a transport fault after kept-call-pace-first
(1 s) doubling to kept-call-pace-max (30 s), each wait within 20 %, until
the caller's bound; past it the answer names every call's time and words.
One journal line per seat at the first fault, then at most once a minute.
The ask id travels in the header x-ask; a holder reads it with
process.AskOf, a bundle with stdio.AskIDOf (TypeScript askIdOf) from the
call's _meta mesh/ask.

Builds: design 47 H2 §775; H-A-351
2026-11-21 23:06:24 +01:00
95 changed files with 12110 additions and 375 deletions
+4
View File
@@ -38,6 +38,10 @@ type Consumer struct {
// and a merge that came back rebuilt what it had just built, five times over on 2026-09-30. // and a merge that came back rebuilt what it had just built, five times over on 2026-09-30.
// With one outstanding, the server holds the rest, and the heartbeat is keeping the message. // With one outstanding, the server holds the rest, and the heartbeat is keeping the message.
MaxAckPending int MaxAckPending int
// InProgressSeconds is how often a holder working a delivery says it is still in progress, so its ack wait does
// not pass while it works (design 47 H2 §777; H-A-340 (1)): the holder's to keep, never sent to the server. Zero
// says nothing.
InProgressSeconds int
// FromNow makes a consumer that does not exist yet start at the stream's end rather than its // FromNow makes a consumer that does not exist yet start at the stream's end rather than its
// beginning (novox/hq issue 248). For a consumer that reacts to announcements — a merge, a build's // beginning (novox/hq issue 248). For a consumer that reacts to announcements — a merge, a build's
// outcome — on a stream that keeps a week of them: the server's default, everything the stream // outcome — on a stream that keeps a week of them: the server's default, everything the stream
+19
View File
@@ -49,4 +49,23 @@ func TestTheBusNamesAgree(t *testing.T) {
t.Errorf("the shared events stream keeps %d s, a seat's definition says %d days", st.MaxAge, seatdef.SharedEventsMaxAgeDays) t.Errorf("the shared events stream keeps %d s, a seat's definition says %d days", st.MaxAge, seatdef.SharedEventsMaxAgeDays)
} }
} }
// Design 47 H2 §777, H-A-362: a seat's work queue and its one worker are derived from its accepted kind's settings;
// absent settings take the defaults, two kinds naming one setting differently are refused, no accept is no queue.
st, w, ok, err := SeatQueue("mesh-builds", []seatdef.Message{{Name: "step", MaxAge: "24h", DuplicatesWindow: "2m",
AckWait: "60s", InProgress: "20s", MaxMsgs: 10000, MaxAckPending: 64, MaxDeliveries: 3}})
if err != nil || !ok || st.Name != "SEAT_MESH_BUILDS" || st.Retention != RetentionWorkQueue || st.MaxAge != 86400 ||
st.MaxMsgs != 10000 || st.DuplicatesSeconds != 120 || st.Subjects[0] != "mesh.seat.mesh-builds.accept.>" ||
w.Name != "SEAT_MESH_BUILDS_worker" || w.Stream != st.Name || w.AckWaitSeconds != 60 || w.MaxDeliver != 3 ||
w.MaxAckPending != 64 || w.InProgressSeconds != 20 {
t.Errorf("derived %+v and %+v, %v", st, w, err)
}
if st, w, _, _ := SeatQueue("mesh-wants", []seatdef.Message{{Name: "step"}}); st.MaxAge != 7*86400 || w.AckWaitSeconds != 60 || w.MaxDeliver != 5 {
t.Errorf("the defaults: %+v, %+v", st, w)
}
if _, _, _, err := SeatQueue("s", []seatdef.Message{{Name: "a", AckWait: "60s"}, {Name: "b", AckWait: "2m"}}); err == nil {
t.Error("two ack waits for one worker were derived")
}
if _, _, ok, _ := SeatQueue("s", nil); ok {
t.Error("a seat that accepts nothing has a queue")
}
} }
+97
View File
@@ -0,0 +1,97 @@
package buscompose
import (
"fmt"
"strings"
"time"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// The work queue's settings where a seat's accepted kinds name none: a week of asks, a delivery given up after five
// handings, a minute before an unacknowledged one is handed again.
const (
SeatQueueDefaultMaxAge = 7 * 24 * time.Hour
SeatQueueDefaultAckWait = time.Minute
SeatQueueDefaultDelivers = 5
)
// SeatQueueStreamName is the stream holding a seat's inbound work, named after the seat, never its holder.
func SeatQueueStreamName(seat string) string { return "SEAT_" + seatUpper(seat) }
// SeatQueueWorkerName is the one worker a seat's holders share on its work queue.
func SeatQueueWorkerName(seat string) string { return "SEAT_" + seatUpper(seat) + "_worker" }
func seatUpper(seat string) string {
return strings.ToUpper(strings.NewReplacer("-", "_", ".", "_").Replace(seat))
}
// SeatQueue derives a seat's work-queue stream and its one shared worker from its accepted kinds' work-queue settings
// (design 47 H2 §777; H-A-350 DMC-1, H-A-362), the one derivation every part takes: max-age, max-msgs and
// duplicates-window bound the stream; ack-wait, max-deliveries, max-ack-pending and in-progress the worker. A setting
// named by two accepted kinds with two values is refused: one stream and one worker carry one value. A seat that
// accepts nothing has no queue (ok false).
func SeatQueue(seat string, accepts []seatdef.Message) (stream Stream, worker Consumer, ok bool, err error) {
if len(accepts) == 0 {
return Stream{}, Consumer{}, false, nil
}
durations := map[string]string{}
counts := map[string]int{}
for _, a := range accepts {
if ps := a.QueueProblems("accepts " + a.Name); len(ps) > 0 {
return Stream{}, Consumer{}, false, fmt.Errorf("the seat %s's work queue: %w", seat, ps)
}
for name, v := range map[string]string{"max-age": a.MaxAge, "duplicates-window": a.DuplicatesWindow,
"ack-wait": a.AckWait, "in-progress": a.InProgress} {
if v == "" {
continue
}
if was, seen := durations[name]; seen && was != v {
return Stream{}, Consumer{}, false, fmt.Errorf("the seat %s's work queue: %s is %s and %s in two accepted kinds", seat, name, was, v)
}
durations[name] = v
}
for name, v := range map[string]int{"max-msgs": a.MaxMsgs, "max-ack-pending": a.MaxAckPending, "max-deliveries": a.MaxDeliveries} {
if v == 0 {
continue
}
if was, seen := counts[name]; seen && was != v {
return Stream{}, Consumer{}, false, fmt.Errorf("the seat %s's work queue: %s is %d and %d in two accepted kinds", seat, name, was, v)
}
counts[name] = v
}
}
seconds := func(name string, def time.Duration) int {
if v, set := durations[name]; set {
d, _ := time.ParseDuration(v) // QueueProblems read it
return int(d / time.Second)
}
return int(def / time.Second)
}
delivers := SeatQueueDefaultDelivers
if v, set := counts["max-deliveries"]; set {
delivers = v
}
subject := "mesh.seat." + seat + ".accept.>"
stream = Stream{
Name: SeatQueueStreamName(seat),
Subjects: []string{subject},
Retention: RetentionWorkQueue,
MaxAge: seconds("max-age", SeatQueueDefaultMaxAge),
MaxMsgs: counts["max-msgs"],
DuplicatesSeconds: seconds("duplicates-window", 0),
Why: fmt.Sprintf("work submitted to the %s seat; one holder consumes it, and it queues while nobody does", seat),
}
worker = Consumer{
Name: SeatQueueWorkerName(seat),
Stream: stream.Name,
Filters: []string{subject},
AckWaitSeconds: seconds("ack-wait", SeatQueueDefaultAckWait),
MaxDeliver: delivers,
MaxAckPending: counts["max-ack-pending"],
InProgressSeconds: seconds("in-progress", 0),
Why: fmt.Sprintf("every holder of %s pulls its asks from this one worker and acknowledges after the work is "+
"done, so a crash mid-work redelivers rather than loses", seat),
}
return stream, worker, true, nil
}
+2
View File
@@ -32,6 +32,8 @@ type Stream struct {
// another's events out of a shared stream. Verified: with a cap of 3, ten messages on one // another's events out of a shared stream. Verified: with a cap of 3, ten messages on one
// subject and one on another leave four in the stream, not three. // subject and one on another leave four in the stream, not three.
MaxMsgsPerSubject int MaxMsgsPerSubject int
// MaxMsgs caps the stream's messages, zero for unbounded: a seat's work queue's max-msgs (design 47 H2 §777).
MaxMsgs int
// Why is carried into the assertion so an operator reading the server's own state finds the // Why is carried into the assertion so an operator reading the server's own state finds the
// reason there, rather than only in a repository they may not have. // reason there, rather than only in a repository they may not have.
Why string Why string
+282 -1
View File
@@ -15,10 +15,15 @@ package busretry
import ( import (
"context" "context"
"encoding/json"
"errors" "errors"
"fmt" "fmt"
"math/rand/v2"
"os" "os"
"sort"
"strings" "strings"
"sync"
"sync/atomic"
"time" "time"
"github.com/nats-io/nats.go" "github.com/nats-io/nats.go"
@@ -36,10 +41,286 @@ var (
// in a process shares, so a test sets them only through it, as t.Cleanup(busretry.Waits(...)): a test that set them // in a process shares, so a test sets them only through it, as t.Cleanup(busretry.Waits(...)): a test that set them
// and left them set shortened the next test's bound to milliseconds, and a loaded check machine overran it (the check // and left them set shortened the next test's bound to milliseconds, and a loaded check machine overran it (the check
// of release sdk1, 2026-11-02). A bound a test waits on to succeed is seconds: no slow machine reaches it. // of release sdk1, 2026-11-02). A bound a test waits on to succeed is seconds: no slow machine reaches it.
// It sets the kept-call pace (KeptPace) to first and most too, so a test of a kept call waits milliseconds.
func Waits(bound, first, most time.Duration) (restore func()) { func Waits(bound, first, most time.Duration) (restore func()) {
was := [3]time.Duration{Bound, FirstWait, MostWait} was := [3]time.Duration{Bound, FirstWait, MostWait}
wasPace := keptPace.Swap(&Pace{First: first, Max: most})
Bound, FirstWait, MostWait = bound, first, most Bound, FirstWait, MostWait = bound, first, most
return func() { Bound, FirstWait, MostWait = was[0], was[1], was[2] } return func() { Bound, FirstWait, MostWait = was[0], was[1], was[2]; keptPace.Store(wasPace) }
}
// Pace is the kept-call form's pace (design 47 H2 §775): on a transport fault the call is made again after First,
// the wait doubling to at most Max, each wait drawn within 20 % of its value so many callers do not call in step.
type Pace struct{ First, Max time.Duration }
// The settings every module using the kept-call form declares, with DefaultPace's values as their defaults (§775).
const (
PaceFirstSetting = "kept-call-pace-first"
PaceMaxSetting = "kept-call-pace-max"
)
// DefaultPace is the pace a module's settings name when they name none (§775): 1 s doubling to 30 s, so a holder
// between two lives (a restart takes 20 to 50 s) is met within one minute without a call a second.
var DefaultPace = Pace{First: time.Second, Max: 30 * time.Second}
// keptPace is the pace ReadPace read, nil until it read one. It is set once and read by every kept call at once, so it
// is held atomically: a kept call on one goroutine never races a Connect or a Serve on another (§782).
var keptPace atomic.Pointer[Pace]
// KeptPace is the pace of every kept call this process makes: DefaultPace until the process reads its settings
// (ReadPace, at process.Connect and at a bundle's stdio.Serve). Safe for concurrent use.
func KeptPace() Pace {
if p := keptPace.Load(); p != nil {
return *p
}
return DefaultPace
}
// ReadPace sets KeptPace from the module's settings PaceFirstSetting and PaceMaxSetting, read through read (the one
// settings reader, stdio.SettingDuration, which answers its default for a setting not composed), so a module's
// declared pace paces its kept calls (§775). A setting that is no duration, or a most below the first, is an error
// naming it, and KeptPace stays. The pace is read once, at the process's start: a later call reading the same pace
// changes nothing, and one reading another pace is refused, naming both, and KeptPace stays (§782). Safe for
// concurrent use.
func ReadPace(read func(key string, def time.Duration) (time.Duration, error)) error {
held := KeptPace()
first, err := read(PaceFirstSetting, held.First)
if err != nil {
return err
}
most, err := read(PaceMaxSetting, held.Max)
if err != nil {
return err
}
if most < first {
return fmt.Errorf("the setting %s (%s) is below %s (%s)", PaceMaxSetting, most, PaceFirstSetting, first)
}
got := Pace{First: first, Max: most}
if keptPace.CompareAndSwap(nil, &got) {
return nil
}
if held = KeptPace(); got != held {
return fmt.Errorf("the kept-call pace is read once, at the start: it is %s to %s, and the settings now say %s to %s",
held.First, held.Max, got.First, got.Max)
}
return nil
}
// The clock and the sleep the paced form waits on; a test of this package replaces both, so nothing sleeps.
var (
now = time.Now
sleep = time.Sleep
)
// jittered is w drawn within 20 % of its value.
func jittered(w time.Duration) time.Duration {
return time.Duration(float64(w) * (0.8 + 0.4*rand.Float64()))
}
// Kept names one kept call of the paced form (design 47 H2 §775): the seat and the verb it asks (named in the journal
// line), the ask's id (named among the asks waiting), the caller's bound (zero is Bound) and the pace (zero is
// KeptPace). Open, when given, makes it asked again only while its key is open (DoKept). Logf is the journal; nil
// writes to standard error.
type Kept struct {
Seat, Verb, Ask string
Bound time.Duration
Pace Pace
Open *Open
Logf func(format string, args ...any)
}
// Try is one call of a kept call that met a transport fault: when it was made and the words it met.
type Try struct {
At time.Time
Words string
}
// Unanswered is a kept call's end past its caller's bound (§775): every call's time and words, so the caller's
// could-not-run or could-not-be-performed names them. It wraps the last fault, so Undelivered and TimedOut read it.
type Unanswered struct {
Seat, Verb, Ask string
Bound time.Duration
Tries []Try
Last error
}
func (u *Unanswered) Error() string {
var b strings.Builder
fmt.Fprintf(&b, "%s.%s", u.Seat, u.Verb)
if u.Ask != "" {
fmt.Fprintf(&b, " (ask %s)", u.Ask)
}
fmt.Fprintf(&b, " unanswered within its bound of %s, called %d times:", u.Bound, len(u.Tries))
for i, t := range u.Tries {
if i > 0 {
b.WriteString(";")
}
fmt.Fprintf(&b, " %s %s", t.At.UTC().Format("15:04:05.000"), t.Words)
}
return b.String()
}
func (u *Unanswered) Unwrap() error { return u.Last }
// Fault says err is a transport fault of a kept call (§775): a request that reached no one, a call's own deadline
// passing, or a holder's answer of the kind away (§776); a callee's refusal never is.
func Fault(err error) bool {
var away *Away
return TimedOut(err) || Undelivered(err) || errors.As(err, &away)
}
// ErrorKindAway is the seat error kind a holder answers when a part it depends on is away (design 47 H2 §776): its
// answer's `error-kind`, beside `part` (what did not answer) and `words`. A caller reads it as a transport fault.
const ErrorKindAway = "away"
// Away is a holder's answer of the kind away, read as an error: the part that did not answer and the holder's words.
type Away struct {
Part, Words string
}
func (a *Away) Error() string {
return fmt.Sprintf("away: %s does not answer: %s", a.Part, a.Words)
}
// AwayAnswer is the seat error answer of the kind away a holder gives (§776): `error` and `error-kind` as each seat's
// error answer has them, with `part` and `words`.
func AwayAnswer(part, words string) map[string]string {
return map[string]string{"error": (&Away{Part: part, Words: words}).Error(), "error-kind": ErrorKindAway,
"part": part, "words": words}
}
// AwayIn is the *Away a verb's answer says when its `error-kind` is away, else nil: an answer that is no object, or
// of another kind, is the caller's to read.
func AwayIn(answer json.RawMessage) *Away {
var a struct {
Error string `json:"error"`
Kind string `json:"error-kind"`
Part string `json:"part"`
Words string `json:"words"`
}
if json.Unmarshal(answer, &a) != nil || a.Kind != ErrorKindAway {
return nil
}
if a.Words == "" {
a.Words = a.Error
}
return &Away{Part: a.Part, Words: a.Words}
}
// DoPaced makes a kept call through try (design 47 H2 §775): on a transport fault (Fault) it calls again at k's pace,
// each wait jittered, until the caller's bound, writing one journal line per seat at the first fault and then at most
// once a minute (the seat, the verb, the asks waiting and the count of calls). Past the bound it returns the last
// answer with an *Unanswered naming every call; a refusal of what was asked returns at once.
func DoPaced[T any](k Kept, try func() (T, error)) (T, error) {
bound, pace := k.Bound, k.Pace
if bound <= 0 {
bound = Bound
}
if pace.First <= 0 || pace.Max <= 0 {
held := KeptPace()
if pace.First <= 0 {
pace.First = held.First
}
if pace.Max <= 0 {
pace.Max = held.Max
}
}
logf := k.Logf
if logf == nil {
logf = func(f string, a ...any) { fmt.Fprintf(os.Stderr, "[mesh-sdk] "+f+"\n", a...) }
}
start, wait := now(), pace.First
var tries []Try
waiting := false
defer func() {
if waiting {
journal.done(k.Seat, k.Ask)
}
}()
for {
at := now()
v, err := try()
if !Fault(err) || (k.Open != nil && !k.Open.stillOpen()) {
return v, err
}
tries = append(tries, Try{At: at, Words: err.Error()})
if !waiting {
journal.wait(k.Seat, k.Ask)
waiting = true
}
journal.fault(k.Seat, k.Verb, logf)
left := bound - now().Sub(start)
if left <= 0 {
return v, &Unanswered{Seat: k.Seat, Verb: k.Verb, Ask: k.Ask, Bound: bound, Tries: tries, Last: err}
}
sleep(min(jittered(wait), left))
wait = min(wait*2, pace.Max)
}
}
// journal holds, per seat, the asks of this process waiting on it through a fault, the calls made since its last
// line and when that line was written: one line per seat at the first fault, then at most once a minute (§775).
var journal = &faults{seats: map[string]*seatFaults{}}
type faults struct {
mu sync.Mutex
seats map[string]*seatFaults
}
type seatFaults struct {
asks map[string]int
calls int
last time.Time
}
func (f *faults) of(seat string) *seatFaults {
s := f.seats[seat]
if s == nil {
s = &seatFaults{asks: map[string]int{}}
f.seats[seat] = s
}
return s
}
func (f *faults) wait(seat, ask string) {
f.mu.Lock()
defer f.mu.Unlock()
f.of(seat).asks[ask]++
}
func (f *faults) done(seat, ask string) {
f.mu.Lock()
defer f.mu.Unlock()
s := f.of(seat)
if s.asks[ask]--; s.asks[ask] <= 0 {
delete(s.asks, ask)
}
}
func (f *faults) fault(seat, verb string, logf func(string, ...any)) {
f.mu.Lock()
s := f.of(seat)
s.calls++
t := now()
if !s.last.IsZero() && t.Sub(s.last) < time.Minute {
f.mu.Unlock()
return
}
s.last = t
var asks []string
n := 0
for a, c := range s.asks {
n += c
if a != "" {
asks = append(asks, a)
}
}
sort.Strings(asks)
calls := s.calls
s.calls = 0
f.mu.Unlock()
logf("kept call: the seat %s does not answer (%s): %d asks waiting %v, %d calls since the last line; called "+
"again at the kept-call pace until each caller's bound", seat, verb, n, asks, calls)
} }
// Undelivered says err means the request reached no one: no responders, JetStream not enabled (for the account), or // Undelivered says err means the request reached no one: no responders, JetStream not enabled (for the account), or
+151
View File
@@ -2,9 +2,11 @@ package busretry
import ( import (
"context" "context"
"encoding/json"
"errors" "errors"
"fmt" "fmt"
"strings" "strings"
"sync"
"testing" "testing"
"time" "time"
@@ -110,8 +112,157 @@ func subAKeptCallIsAskedAgainOnlyWhileItsKeyIsOpen(t *testing.T) {
} }
} }
// fakeClock replaces the paced form's clock and sleep for one test: a sleep moves the clock, nothing sleeps.
func fakeClock(t *testing.T) (slept *[]time.Duration) {
at := time.Date(2026, 11, 21, 22, 0, 0, 0, time.UTC)
waits := []time.Duration{}
wasNow, wasSleep, wasJournal := now, sleep, journal
now = func() time.Time { return at }
sleep = func(d time.Duration) { waits = append(waits, d); at = at.Add(d) }
journal = &faults{seats: map[string]*seatFaults{}}
t.Cleanup(func() { now, sleep, journal = wasNow, wasSleep, wasJournal })
return &waits
}
// Design 47 H2 §775: the kept call is paced from 1 s doubling to 30 s, each wait within 20 %; met by no responders twice
// and then answered it returns the answer and writes one journal line; past its caller's bound it returns every try;
// a refusal returns at once; the journal says a seat at most once a minute.
func subAKeptCallIsPaced(t *testing.T) {
t.Run("no responders twice, then answered: the answer and one line", func(t *testing.T) {
slept := fakeClock(t)
tries, logs := 0, []string{}
v, err := DoPaced(Kept{Seat: "mesh-builds", Verb: "build", Ask: "a1", Bound: time.Minute,
Logf: func(f string, a ...any) { logs = append(logs, fmt.Sprintf(f, a...)) }}, func() (int, error) {
if tries++; tries <= 2 {
return 0, nats.ErrNoResponders
}
return 7, nil
})
if v != 7 || err != nil || tries != 3 || len(logs) != 1 || !strings.Contains(logs[0], "mesh-builds") ||
!strings.Contains(logs[0], "build") || !strings.Contains(logs[0], "[a1]") {
t.Fatalf("%d, %v after %d tries, logs %q", v, err, tries, logs)
}
for i, base := range []time.Duration{time.Second, 2 * time.Second} {
if w := (*slept)[i]; w < base*8/10 || w > base*12/10 {
t.Errorf("wait %d is %s, not within 20 %% of %s", i, w, base)
}
}
})
t.Run("past its bound: every try", func(t *testing.T) {
slept := fakeClock(t)
tries := 0
_, err := DoPaced(Kept{Seat: "mesh-wants", Verb: "compose-candidate", Ask: "a2", Bound: 3 * time.Minute,
Logf: func(string, ...any) {}}, func() (int, error) { tries++; return 0, context.DeadlineExceeded })
var u *Unanswered
if !errors.As(err, &u) || len(u.Tries) != tries || tries < 5 || !TimedOut(err) ||
!strings.Contains(err.Error(), "context deadline exceeded") {
t.Fatalf("%d tries: %v", tries, err)
}
for _, w := range *slept {
if w > 30*time.Second*12/10 {
t.Errorf("a wait of %s passes the pace's most", w)
}
}
})
t.Run("a refusal returns at once", func(t *testing.T) {
slept := fakeClock(t)
tries := 0
_, err := DoPaced(Kept{Seat: "git", Verb: "merge"}, func() (int, error) { tries++; return 0, &Answered{Words: "refused"} })
if tries != 1 || len(*slept) != 0 || err == nil {
t.Fatalf("%d tries, %v", tries, err)
}
})
t.Run("away is a transport fault; its answer reads back", func(t *testing.T) {
raw, _ := json.Marshal(AwayAnswer("the forge's store", "401 and the version read failed"))
a := AwayIn(raw)
if a == nil || a.Part != "the forge's store" || a.Words != "401 and the version read failed" || !Fault(a) ||
!strings.Contains(string(raw), `"error-kind":"away"`) {
t.Fatalf("%s read as %+v", raw, a)
}
if AwayIn([]byte(`{"error":"no","error-kind":"refused"}`)) != nil || AwayIn([]byte(`[1]`)) != nil || Fault(&Answered{Words: "away"}) {
t.Fatal("a refusal reads as away")
}
if a := AwayIn([]byte(`{"error":"the store is down","error-kind":"away"}`)); a == nil || a.Words != "the store is down" {
t.Fatalf("an away answer with no words reads %+v", a)
}
})
t.Run("the pace is the module's settings", func(t *testing.T) {
was := keptPace.Load()
t.Cleanup(func() { keptPace.Store(was) })
reader := func(set map[string]time.Duration) func(string, time.Duration) (time.Duration, error) {
return func(key string, def time.Duration) (time.Duration, error) {
if d, ok := set[key]; ok {
if d < 0 {
return 0, fmt.Errorf("the setting %s is no duration", key)
}
return d, nil
}
return def, nil
}
}
two := map[string]time.Duration{PaceFirstSetting: 2 * time.Second, PaceMaxSetting: time.Minute}
for _, c := range []struct {
name string
held *Pace // the pace read before, nil none
set map[string]time.Duration
bad string
want Pace
}{
{name: "none set", want: DefaultPace},
{name: "both set", set: two, want: Pace{First: 2 * time.Second, Max: time.Minute}},
{name: "most below first", set: map[string]time.Duration{PaceFirstSetting: time.Minute, PaceMaxSetting: time.Second}, bad: "is below", want: DefaultPace},
{name: "no duration", set: map[string]time.Duration{PaceFirstSetting: -1}, bad: "no duration", want: DefaultPace},
// Design 47 H2 §782: the pace is read once; a later read of the same pace changes nothing, of another is refused.
{name: "read again, the same", held: &Pace{First: 2 * time.Second, Max: time.Minute}, set: two, want: Pace{First: 2 * time.Second, Max: time.Minute}},
{name: "read again, none set", held: &Pace{First: 2 * time.Second, Max: time.Minute}, want: Pace{First: 2 * time.Second, Max: time.Minute}},
{name: "read again, another", held: &DefaultPace, set: two, bad: "read once", want: DefaultPace},
} {
keptPace.Store(c.held)
err := ReadPace(reader(c.set))
if (err != nil) != (c.bad != "") || (err != nil && !strings.Contains(err.Error(), c.bad)) || KeptPace() != c.want {
t.Errorf("%s: pace %+v, %v", c.name, KeptPace(), err)
}
}
// Design 47 H2 §782, under -race: a Connect or a Serve reading the pace while kept calls read it is no data race.
keptPace.Store(nil)
var wg sync.WaitGroup
for i := range 8 {
wg.Add(2)
go func() { defer wg.Done(); _ = ReadPace(reader(two)) }()
go func() {
defer wg.Done()
if _, err := DoPaced(Kept{Seat: "s", Verb: fmt.Sprint(i), Logf: func(string, ...any) {}}, func() (int, error) { return 1, nil }); err != nil {
t.Error(err)
}
_ = KeptPace()
}()
}
wg.Wait()
if KeptPace() != (Pace{First: 2 * time.Second, Max: time.Minute}) {
t.Errorf("after concurrent reads the pace is %+v", KeptPace())
}
})
t.Run("one line per seat a minute", func(t *testing.T) {
fakeClock(t)
logs := 0
k := Kept{Seat: "mesh-builds", Verb: "build", Bound: 10 * time.Second, Logf: func(string, ...any) { logs++ }}
fail := func() (int, error) { return 0, nats.ErrNoResponders }
_, _ = DoPaced(k, fail)
_, _ = DoPaced(k, fail)
if logs != 1 {
t.Fatalf("%d lines within a minute", logs)
}
k.Bound = 2 * time.Minute
_, _ = DoPaced(k, fail)
if logs < 2 {
t.Fatalf("%d lines past a minute", logs)
}
})
}
// TestABusThatAnswersNothingIsWaitedOut runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest. // TestABusThatAnswersNothingIsWaitedOut runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
func TestABusThatAnswersNothingIsWaitedOut(t *testing.T) { func TestABusThatAnswersNothingIsWaitedOut(t *testing.T) {
t.Run("ABusThatAnswersNothingIsWaitedOut", subABusThatAnswersNothingIsWaitedOut) t.Run("ABusThatAnswersNothingIsWaitedOut", subABusThatAnswersNothingIsWaitedOut)
t.Run("AKeptCallIsAskedAgainOnlyWhileItsKeyIsOpen", subAKeptCallIsAskedAgainOnlyWhileItsKeyIsOpen) t.Run("AKeptCallIsAskedAgainOnlyWhileItsKeyIsOpen", subAKeptCallIsAskedAgainOnlyWhileItsKeyIsOpen)
t.Run("AKeptCallIsPaced", subAKeptCallIsPaced)
} }
+7
View File
@@ -78,6 +78,13 @@ func (o Objects) Delete(name string) error {
return err return err
} }
// Purge removes what the deleted object name left behind in the store, its chunks, through the runtime's delete, which
// purges them again when asked again (H-A-366): a bundle never opens a connection of its own for it.
func (o Objects) Purge(name string) error {
_, err := call[buscalls.Done](buscalls.ObjectsDelete, buscalls.ObjectsNameRequest{Objects: o.local, Name: name})
return err
}
// Fill is how much the store holds against its cap. // Fill is how much the store holds against its cap.
func (o Objects) Fill() (buscalls.Fill, error) { func (o Objects) Fill() (buscalls.Fill, error) {
return call[buscalls.Fill](buscalls.ObjectsInfo, buscalls.ObjectsRequest{Objects: o.local}) return call[buscalls.Fill](buscalls.ObjectsInfo, buscalls.ObjectsRequest{Objects: o.local})
+6 -2
View File
@@ -35,6 +35,7 @@ func subABundleKeepsObjectsThroughTheRuntime(t *testing.T) {
list, err := in.List() list, err := in.List()
results <- result{"list", err, len(list)} results <- result{"list", err, len(list)}
results <- result{"delete", in.Delete("t1.part0"), nil} results <- result{"delete", in.Delete("t1.part0"), nil}
results <- result{"purge", in.Purge("t1.part0"), nil} // H-A-366
fill, err := in.Fill() fill, err := in.Fill()
results <- result{"fill", err, fill.MaxBytes} results <- result{"fill", err, fill.MaxBytes}
_, err = stdio.BusState("mesh/state.get", nil) _, err = stdio.BusState("mesh/state.get", nil)
@@ -81,8 +82,8 @@ func subABundleKeepsObjectsThroughTheRuntime(t *testing.T) {
asked[method] = p asked[method] = p
send(map[string]any{"jsonrpc": "2.0", "id": m["id"], "result": answers[method]}) send(map[string]any{"jsonrpc": "2.0", "id": m["id"], "result": answers[method]})
} }
want := map[string]any{"put": "SHA-256=x", "get": "hello", "list": 1, "delete": nil, "fill": uint64(20 << 30)} want := map[string]any{"put": "SHA-256=x", "get": "hello", "list": 1, "delete": nil, "purge": nil, "fill": uint64(20 << 30)}
for range 5 { for range 6 {
r := <-results r := <-results
if r.err != nil || r.got != want[r.what] { if r.err != nil || r.got != want[r.what] {
t.Errorf("%s answered %v, %v; want %v", r.what, r.got, r.err, want[r.what]) t.Errorf("%s answered %v, %v; want %v", r.what, r.got, r.err, want[r.what])
@@ -96,6 +97,9 @@ func subABundleKeepsObjectsThroughTheRuntime(t *testing.T) {
t.Errorf("%s named the store %v, not its local name", method, p["objects"]) t.Errorf("%s named the store %v, not its local name", method, p["objects"])
} }
} }
if p := asked[buscalls.ObjectsDelete]; p["name"] != "t1.part0" {
t.Errorf("delete and purge asked %v", p)
}
if p := asked[buscalls.ObjectsPut]; p["name"] != "t1.part0" || p["data"] != "aGVsbG8=" || p["description"] != "a part" { if p := asked[buscalls.ObjectsPut]; p["name"] != "t1.part0" || p["data"] != "aGVsbG8=" || p["description"] != "a part" {
t.Errorf("put asked %v", p) t.Errorf("put asked %v", p)
} }
+32 -3
View File
@@ -28,11 +28,19 @@ var busUser = regexp.MustCompile(`^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$`)
// buscalls.MetaCall, written here too so this package imports nothing of buscalls. // buscalls.MetaCall, written here too so this package imports nothing of buscalls.
const MetaCall = "mesh/call" const MetaCall = "mesh/call"
// AskHeader is the bus header a kept call carries its ask's id in (design 47 H2 §775; H-A-351): a holder in a process
// reads it with process.AskOf, and the tool runner copies it into a `tools/call`'s `_meta` under MetaAsk, read with
// AskIDOf.
const AskHeader = "x-ask"
// MetaAsk is where in a `tools/call`'s `_meta` the runtime names the ask id the call carried in AskHeader (H-A-351).
const MetaAsk = "mesh/ask"
// callID is the shape of a call's id: one subject-safe token, as the runtime makes it. Anything else reads as none. // callID is the shape of a call's id: one subject-safe token, as the runtime makes it. Anything else reads as none.
var callID = regexp.MustCompile(`^[A-Za-z0-9_-]{1,128}$`) var callID = regexp.MustCompile(`^[A-Za-z0-9_-]{1,128}$`)
// inFlight is what the runtime said of one call while its tool runs. // inFlight is what the runtime said of one call while its tool runs.
type inFlight struct{ caller, call string } type inFlight struct{ caller, call, ask string }
// calls holds the caller and the id of every call while its tool runs, by the arguments map that call was handed. // calls holds the caller and the id of every call while its tool runs, by the arguments map that call was handed.
var calls sync.Map // unsafe.Pointer → inFlight var calls sync.Map // unsafe.Pointer → inFlight
@@ -75,6 +83,27 @@ func callIn(meta map[string]any) string {
return "" return ""
} }
// AskIDOf is the ask id the call that was handed args carried (design 47 H2 §775; H-A-351): what the kept call set in
// AskHeader and the runtime named under MetaAsk, by which a holder takes the ask once. Empty when the call
// carried none. Valid while the tool runs.
func AskIDOf(args map[string]any) string {
if args == nil {
return ""
}
if c, ok := calls.Load(argsKey(args)); ok {
return c.(inFlight).ask
}
return ""
}
// askIn is the ask id a `tools/call`'s `_meta` names, or empty: one subject-safe token, as a call's id is.
func askIn(meta map[string]any) string {
if s, ok := meta[MetaAsk].(string); ok && callID.MatchString(s) {
return s
}
return ""
}
// callerIn is the caller a `tools/call`'s `_meta` names, or Unproven. // callerIn is the caller a `tools/call`'s `_meta` names, or Unproven.
func callerIn(meta map[string]any) string { func callerIn(meta map[string]any) string {
if s, ok := meta[MetaCaller].(string); ok && busUser.MatchString(s) { if s, ok := meta[MetaCaller].(string); ok && busUser.MatchString(s) {
@@ -84,9 +113,9 @@ func callerIn(meta map[string]any) string {
} }
// runAs runs a tool with the caller and the call's id held for its arguments for as long as it runs. // runAs runs a tool with the caller and the call's id held for its arguments for as long as it runs.
func runAs(t Tool, caller, call string, args map[string]any) (any, error) { func runAs(t Tool, f inFlight, args map[string]any) (any, error) {
key := argsKey(args) key := argsKey(args)
calls.Store(key, inFlight{caller, call}) calls.Store(key, f)
defer calls.Delete(key) defer calls.Delete(key)
return t.Run(args) return t.Run(args)
} }
+43 -8
View File
@@ -4,6 +4,7 @@ import (
"bufio" "bufio"
"encoding/json" "encoding/json"
"io" "io"
"strings"
"testing" "testing"
"time" "time"
@@ -13,26 +14,26 @@ import (
// callWith serves one tool that answers the caller CallerOf reads from its arguments, sends it one tools/call // callWith serves one tool that answers the caller CallerOf reads from its arguments, sends it one tools/call
// with the params given, and returns the caller it answered. // with the params given, and returns the caller it answered.
func callWith(t *testing.T, params map[string]any) string { func callWith(t *testing.T, params map[string]any) string {
caller, _ := callAnswering(t, params) caller, _, _ := callAnswering(t, params)
return caller return caller
} }
// callAnswering is callWith answering the call's id CallIDOf read too. // callAnswering is callWith answering the call's id CallIDOf read too.
func callAnswering(t *testing.T, params map[string]any) (string, string) { func callAnswering(t *testing.T, params map[string]any) (string, string, string) {
servesAlone(t) servesAlone(t)
t.Helper() t.Helper()
inR, inW := io.Pipe() inR, inW := io.Pipe()
outR, outW := io.Pipe() outR, outW := io.Pipe()
go func() { go func() {
_ = ServeOn("tracker", []Tool{{Name: "who", Run: func(args map[string]any) (any, error) { _ = ServeOn("tracker", []Tool{{Name: "who", Run: func(args map[string]any) (any, error) {
return map[string]any{"caller": CallerOf(args), "call": CallIDOf(args)}, nil return map[string]any{"caller": CallerOf(args), "call": CallIDOf(args), "ask": AskIDOf(args)}, nil
}}}, inR, outW) }}}, inR, outW)
}() }()
defer inW.Close() defer inW.Close()
b, _ := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": params}) b, _ := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": params})
_, _ = inW.Write(append(b, '\n')) _, _ = inW.Write(append(b, '\n'))
lines := bufio.NewScanner(outR) lines := bufio.NewScanner(outR)
done := make(chan [2]string, 1) done := make(chan [3]string, 1)
go func() { go func() {
if lines.Scan() { if lines.Scan() {
var m struct { var m struct {
@@ -46,19 +47,20 @@ func callAnswering(t *testing.T, params map[string]any) (string, string) {
var answer struct { var answer struct {
Caller string `json:"caller"` Caller string `json:"caller"`
Call string `json:"call"` Call string `json:"call"`
Ask string `json:"ask"`
} }
if len(m.Result.Content) > 0 { if len(m.Result.Content) > 0 {
_ = json.Unmarshal([]byte(m.Result.Content[0].Text), &answer) _ = json.Unmarshal([]byte(m.Result.Content[0].Text), &answer)
} }
done <- [2]string{answer.Caller, answer.Call} done <- [3]string{answer.Caller, answer.Call, answer.Ask}
} }
}() }()
select { select {
case got := <-done: case got := <-done:
return got[0], got[1] return got[0], got[1], got[2]
case <-time.After(3 * time.Second): case <-time.After(3 * time.Second):
t.Fatal("the bundle did not answer the call") t.Fatal("the bundle did not answer the call")
return "", "" return "", "", ""
} }
} }
@@ -83,13 +85,46 @@ func TestAToolReadsTheCallerTheRuntimeNamed(t *testing.T) {
{map[string]any{}, map[string]any{MetaCall: "a b"}, ""}, {map[string]any{}, map[string]any{MetaCall: "a b"}, ""},
{map[string]any{}, map[string]any{MetaCall: 7}, ""}, {map[string]any{}, map[string]any{MetaCall: 7}, ""},
} { } {
if _, call := callAnswering(t, map[string]any{"name": "who", "arguments": c.args, "_meta": c.meta}); call != c.want { if _, call, _ := callAnswering(t, map[string]any{"name": "who", "arguments": c.args, "_meta": c.meta}); call != c.want {
t.Errorf("args %v, meta %v: the tool read call %q, want %q", c.args, c.meta, call, c.want) t.Errorf("args %v, meta %v: the tool read call %q, want %q", c.args, c.meta, call, c.want)
} }
} }
// Design 47 H2 §775, H-A-351: the ask id a kept call carried is the runtime's to name under mesh/ask, never the
// arguments'.
for _, c := range []struct {
args, meta map[string]any
want string
}{
{map[string]any{}, map[string]any{MetaAsk: "build-7Hq2"}, "build-7Hq2"},
{map[string]any{MetaAsk: "forged"}, map[string]any{}, ""},
{map[string]any{}, map[string]any{MetaAsk: "a.b"}, ""},
} {
if _, _, ask := callAnswering(t, map[string]any{"name": "who", "arguments": c.args, "_meta": c.meta}); ask != c.want {
t.Errorf("args %v, meta %v: the tool read ask %q, want %q", c.args, c.meta, ask, c.want)
}
}
if CallIDOf(map[string]any{"x": 1}) != "" || CallIDOf(nil) != "" { if CallIDOf(map[string]any{"x": 1}) != "" || CallIDOf(nil) != "" {
t.Error("arguments no call was handed have a call id") t.Error("arguments no call was handed have a call id")
} }
// Design 47 H2 §781, H-A-370: a process and a bundle read a setting by its key from the word the node-engine composes.
t.Setenv("MESH_CONFIG_ASK_UNANSWERED_BOUND", "10m")
t.Setenv("MESH_CONFIG_KEPT_CALL_PACE_FIRST", "soon")
if v, ok := Setting("ask-unanswered-bound"); !ok || v != "10m" {
t.Errorf("the setting read %q, %v", v, ok)
}
if d, err := SettingDuration("ask-unanswered-bound", time.Minute); err != nil || d != 10*time.Minute {
t.Errorf("the duration read %s, %v", d, err)
}
if d, err := SettingDuration("compose-ask-bound", 10*time.Second); err != nil || d != 10*time.Second {
t.Errorf("an absent setting read %s, %v, not its default", d, err)
}
if _, err := SettingDuration("kept-call-pace-first", time.Second); err == nil || !strings.Contains(err.Error(), "kept-call-pace-first") {
t.Errorf("a value that is no duration read as %v", err)
}
// §775: a bundle reads its kept-call pace from the same settings at its start, and refuses one that is no duration.
if err := ServeOn("b", nil, strings.NewReader(""), io.Discard); err == nil || !strings.Contains(err.Error(), "kept-call-pace-first") {
t.Errorf("a bundle served with a pace that is no duration: %v", err)
}
if MetaCall != buscalls.MetaCall { if MetaCall != buscalls.MetaCall {
t.Errorf("the call id's place is %q here and %q in buscalls", MetaCall, buscalls.MetaCall) t.Errorf("the call id's place is %q here and %q in buscalls", MetaCall, buscalls.MetaCall)
} }
+58
View File
@@ -0,0 +1,58 @@
package catalogue
import (
"encoding/json"
"strconv"
)
// Every kept store of a delivery module names its cap (design 47 H2 §812, §814): the manifest validator refuses a
// delivery module's state, log or objects entry with no cap. This is what it reads of a manifest; which module is a
// delivery module (one claiming a seat of the delivery system) and the foundation parts' old sections are its own to
// judge.
// Uncapped is one state, log or objects entry of a manifest that names no cap.
type Uncapped struct {
// Name is the entry's local name.
Name string `json:"name"`
// Kind is state, log or objects (the template's, or the old section's).
Kind string `json:"kind"`
// OldSection says the entry is in the old section of its kind (`state`, `logs`, `objects`), not an entry of
// `requires`.
OldSection bool `json:"old-section,omitempty"`
}
// UncappedStores is every state, log and objects entry of m that names no cap, the old sections' (max-mib) and the
// bus-state entries' (the option max-mib) alike, in the manifest's order. A log's default cap is not one it names.
func (m Manifest) UncappedStores() []Uncapped {
var out []Uncapped
for _, s := range m.State {
if s.MaxMiB == 0 {
out = append(out, Uncapped{Name: s.Name, Kind: TemplateState, OldSection: true})
}
}
for _, l := range m.Logs {
if l.MaxMiB == 0 {
out = append(out, Uncapped{Name: l.Name, Kind: TemplateLog, OldSection: true})
}
}
for _, o := range m.Objects {
if o.MaxMiB == 0 {
out = append(out, Uncapped{Name: o.Name, Kind: TemplateObjects, OldSection: true})
}
}
for _, e := range m.BusState {
switch e.Template {
case TemplateState, TemplateLog, TemplateObjects:
if !namesCap(e.Options[OptionCapMiB]) {
out = append(out, Uncapped{Name: e.Name, Kind: e.Template})
}
}
}
return out
}
// namesCap is whether an option's value is a cap above zero.
func namesCap(raw json.RawMessage) bool {
n, err := strconv.ParseFloat(string(raw), 64)
return err == nil && n > 0
}
+10 -4
View File
@@ -3,6 +3,7 @@ package catalogue
import ( import (
"bytes" "bytes"
"encoding/json" "encoding/json"
"slices"
"strings" "strings"
"testing" "testing"
) )
@@ -135,10 +136,10 @@ func TestAConfigManifestIsWrittenBackInItsOwnForm(t *testing.T) {
// The registry milestone's words round-trip the same (design 32): a config value's old name, an artifact's series // The registry milestone's words round-trip the same (design 32): a config value's old name, an artifact's series
// and contracts marker, the series a module accepts of a package; absent, a series is 0.1. // and contracts marker, the series a module accepts of a package; absent, a series is 0.1.
declared := []byte(`{"module":"c","version":"1","config":{"font":{"type":"string","renamed-from":"font-name"}}, declared := []byte(`{"module":"c","version":"1","check-needs":["node-build-node"],"config":{"font":{"type":"string","renamed-from":"font-name"}},
"packages":{"mesh-sdk":"0.2"}, "packages":{"mesh-sdk":"0.2"},
"build":{"artifacts":[{"name":"go","kind":"package","language":"go","paths":["go"],"series":"0.2", "build":{"artifacts":[{"name":"go","kind":"package","language":"go","paths":["go"],"series":"0.2",
"generated-from":"seats"},{"name":"lib","kind":"package","language":"typescript"}]}}`) "generated-from":"seats","check-needs":["node-build-node"]},{"name":"lib","kind":"package","language":"typescript"}]}}`)
m, err = decodeForTest(declared) m, err = decodeForTest(declared)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
@@ -146,16 +147,21 @@ func TestAConfigManifestIsWrittenBackInItsOwnForm(t *testing.T) {
if m.Settings["font"].RenamedFrom != "font-name" || m.AcceptedSeries("mesh-sdk") != "0.2" || if m.Settings["font"].RenamedFrom != "font-name" || m.AcceptedSeries("mesh-sdk") != "0.2" ||
m.AcceptedSeries("mesh-contracts") != DefaultSeries || m.Build.Artifacts[0].SeriesOf() != "0.2" || m.AcceptedSeries("mesh-contracts") != DefaultSeries || m.Build.Artifacts[0].SeriesOf() != "0.2" ||
m.AcceptedSeries("mesh-sdk", "0.1") != "0.2" || m.AcceptedSeries("mesh-contracts", "0.10", "x", "0.3", "1.0") != "0.3" || m.AcceptedSeries("mesh-sdk", "0.1") != "0.2" || m.AcceptedSeries("mesh-contracts", "0.10", "x", "0.3", "1.0") != "0.3" ||
m.Build.Artifacts[0].GeneratedFrom != "seats" || m.Build.Artifacts[1].SeriesOf() != "0.1" { m.Build.Artifacts[0].GeneratedFrom != "seats" || m.Build.Artifacts[1].SeriesOf() != "0.1" ||
!slices.Equal(m.Build.Artifacts[0].CheckNeeds, []string{"node-build-node"}) || m.Build.Artifacts[1].CheckNeeds != nil ||
!slices.Equal(m.CheckNeeds, []string{"node-build-node"}) {
t.Fatalf("read %+v", m) t.Fatalf("read %+v", m)
} }
raw, _ = json.Marshal(m) raw, _ = json.Marshal(m)
for _, said := range []string{`"renamed-from":"font-name"`, `"packages":{"mesh-sdk":"0.2"}`, `"series":"0.2"`, for _, said := range []string{`"renamed-from":"font-name"`, `"packages":{"mesh-sdk":"0.2"}`, `"series":"0.2"`,
`"generated-from":"seats"`} { `"generated-from":"seats"`, `"check-needs":["node-build-node"]`} {
if !strings.Contains(string(raw), said) { if !strings.Contains(string(raw), said) {
t.Errorf("written back without %s: %s", said, raw) t.Errorf("written back without %s: %s", said, raw)
} }
} }
if strings.Count(string(raw), `"check-needs":["node-build-node"]`) != 2 { // H-A-453 (2): the module's own and the artifact's
t.Errorf("the module's check-needs is not written back: %s", raw)
}
if strings.Count(string(raw), `"series"`) != 1 { if strings.Count(string(raw), `"series"`) != 1 {
t.Errorf("a series nobody said is written: %s", raw) t.Errorf("a series nobody said is written: %s", raw)
} }
+31
View File
@@ -452,6 +452,15 @@ func (m Manifest) AnsweredByHelperFor(provision string) bool {
return false return false
} }
// The classes a module is (Manifest.Class; design 47 H2 §810, H-A-394).
const (
ClassCore = "core"
ClassLeaf = "leaf"
)
// Leaf is whether m is a leaf: its class says so, or it names none.
func (m Manifest) Leaf() bool { return m.Class == "" || m.Class == ClassLeaf }
// Manifest is everything a module says about itself. // Manifest is everything a module says about itself.
type Manifest struct { type Manifest struct {
Module string `json:"module"` Module string `json:"module"`
@@ -737,6 +746,11 @@ type Manifest struct {
// wrong the moment anybody edits anything. // wrong the moment anybody edits anything.
Build *Build `json:"build,omitempty"` Build *Build `json:"build,omitempty"`
// CheckNeeds are the seats the integration tests of a package outside every artifact's `from` need the node to hold, by
// name, in an artifact's form (Artifact.CheckNeeds): the Go build module reads them for the packages no artifact's
// `from` holds (design 47 H2 H-A-453 (2)). Empty needs nothing.
CheckNeeds []string `json:"check-needs,omitempty"`
// Templates is the module's directory its template files are kept in, and its build packs into its templates // Templates is the module's directory its template files are kept in, and its build packs into its templates
// archive: files/ when it says none (DefaultTemplatesDir; novox/hq ADR 0349 §2, issue 731). A module whose files/ // archive: files/ when it says none (DefaultTemplatesDir; novox/hq ADR 0349 §2, issue 731). A module whose files/
// is already an archive unpacked onto the machine names another, so its templates neither land beside what it // is already an archive unpacked onto the machine names another, so its templates neither land beside what it
@@ -823,6 +837,18 @@ type Manifest struct {
// no module): the bus and the provisioner and its client say it. // no module): the bus and the provisioner and its client say it.
CoreCredentials bool `json:"core-credentials,omitempty"` CoreCredentials bool `json:"core-credentials,omitempty"`
// DeclarationReads is the declaration Version (declaration.Version) the node-engine this module is reads, and
// DeclarationWrites the one the composer this module is writes (design 47 H2 §813 (12), H-A-388): the edge the delivery
// plan derives orders the writer of a Version after every node's engine that reads it. Said by the module; zero for
// one that is neither.
DeclarationReads int `json:"declaration-reads,omitempty"`
DeclarationWrites int `json:"declaration-writes,omitempty"`
// Class is ClassCore for a module whose delivery carries a contract of the mesh (one that claims a seat) and
// ClassLeaf for one that claims none (design 47 H2 §810, H-A-394): the gate reads it from the module's catalog
// entry. Absent is a leaf (Leaf); which manifest must name it is the manifest check's.
Class string `json:"class,omitempty"`
// SecretsOwner is who the files holding this module's secrets belong to on the machine — // SecretsOwner is who the files holding this module's secrets belong to on the machine —
// `uid:gid`, or a name — when its process is not root. // `uid:gid`, or a name — when its process is not root.
// //
@@ -1263,6 +1289,11 @@ type Artifact struct {
// module carrying it holds contracts only and claims no seat, which the judge refuses naming the seat; the build // module carrying it holds contracts only and claims no seat, which the judge refuses naming the seat; the build
// modules' test step regenerates the package and fails on a file out of step. // modules' test step regenerates the package and fails on a file out of step.
GeneratedFrom string `json:"generated-from,omitempty"` GeneratedFrom string `json:"generated-from,omitempty"`
// CheckNeeds are the seats a Go artifact's integration tests need the node to hold, by name (`node-build-node`), as the
// marker file check-needs in a package's directory named them, which this field replaces (design 47 H2 §800; H-A-350
// DMC-6, H-A-399 (3)); the Go build module's digest and the delivery SDK's step run read it here. Empty needs nothing.
CheckNeeds []string `json:"check-needs,omitempty"`
} }
// AcceptedSeries is the series of the package of that name this module accepts: the one Packages names, or else the // AcceptedSeries is the series of the package of that name this module accepts: the one Packages names, or else the
+1
View File
@@ -303,6 +303,7 @@ word:slug
word:state word:state
word:state.history word:state.history
word:state.key-ttl word:state.key-ttl
word:state.max-mib
word:state.name word:state.name
word:state.per-machine word:state.per-machine
word:state.ttl-seconds word:state.ttl-seconds
+6 -5
View File
@@ -7,7 +7,8 @@ import (
) )
// The service manager is a seat of the mesh's own with the unit verbs as its contract (novox/hq // The service manager is a seat of the mesh's own with the unit verbs as its contract (novox/hq
// ADR 0177): every verb described, with a schema, taking a scope. // ADR 0177): every verb described, with a schema, taking a scope but kernel-log, the kernel's messages, which no user
// unit has (issue 1975).
func TestTheServiceManagerSeatServesTheUnitVerbs(t *testing.T) { func TestTheServiceManagerSeatServesTheUnitVerbs(t *testing.T) {
seat, ok := SeatNamed("node-service-manager") seat, ok := SeatNamed("node-service-manager")
if !ok { if !ok {
@@ -16,7 +17,7 @@ func TestTheServiceManagerSeatServesTheUnitVerbs(t *testing.T) {
if seat.Scope != ScopeNode { if seat.Scope != ScopeNode {
t.Fatalf("the service manager is a role each machine has once, and the seat is %s-scoped", seat.Scope) t.Fatalf("the service manager is a role each machine has once, and the seat is %s-scoped", seat.Scope)
} }
want := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "failed", "reset-failed", "wanted-by", "unlink-dangling"} want := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "kernel-log", "failed", "reset-failed", "wanted-by", "unlink-dangling"}
var got []string var got []string
for _, v := range seat.Serves { for _, v := range seat.Serves {
got = append(got, v.Name) got = append(got, v.Name)
@@ -24,7 +25,7 @@ func TestTheServiceManagerSeatServesTheUnitVerbs(t *testing.T) {
t.Fatalf("%s is promised without a description or a schema", v.Name) t.Fatalf("%s is promised without a description or a schema", v.Name)
} }
props, _ := v.Input["properties"].(map[string]any) props, _ := v.Input["properties"].(map[string]any)
if _, has := props["scope"]; !has { if _, has := props["scope"]; !has && v.Name != "kernel-log" {
t.Fatalf("%s takes no scope, and a user unit could not be asked for", v.Name) t.Fatalf("%s takes no scope, and a user unit could not be asked for", v.Name)
} }
} }
@@ -41,7 +42,7 @@ func TestFailedIsAnOptionalVerbOfTheServiceManager(t *testing.T) {
holder := func(serves ...string) Manifest { holder := func(serves ...string) Manifest {
return Manifest{Module: "systemd", Version: "1", Claims: []Claim{{Name: ServiceManagerSeat, Scope: ScopeNode, Serves: serves}}} return Manifest{Module: "systemd", Version: "1", Claims: []Claim{{Name: ServiceManagerSeat, Scope: ScopeNode, Serves: serves}}}
} }
eight := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", eight := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "kernel-log",
"reset-failed", "wanted-by", "unlink-dangling"} "reset-failed", "wanted-by", "unlink-dangling"}
if err := CanHold(holder(eight...), seat); err != nil { if err := CanHold(holder(eight...), seat); err != nil {
t.Fatalf("a holder without failed is refused: %v", err) t.Fatalf("a holder without failed is refused: %v", err)
@@ -69,7 +70,7 @@ func TestFailedIsAnOptionalVerbOfTheServiceManager(t *testing.T) {
// back from the store's row they stay required. // back from the store's row they stay required.
func TestResetFailedWantedByAndUnlinkDanglingAreRequiredVerbsOfTheServiceManager(t *testing.T) { func TestResetFailedWantedByAndUnlinkDanglingAreRequiredVerbsOfTheServiceManager(t *testing.T) {
defer UseSeats(DefaultSeats()) defer UseSeats(DefaultSeats())
nine := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "failed"} nine := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "kernel-log", "failed"}
all := append(slices.Clone(nine), "reset-failed", "wanted-by", "unlink-dangling") all := append(slices.Clone(nine), "reset-failed", "wanted-by", "unlink-dangling")
holder := func(serves ...string) Manifest { holder := func(serves ...string) Manifest {
return Manifest{Module: "systemd", Version: "1", Claims: []Claim{{Name: ServiceManagerSeat, Scope: ScopeNode, Serves: serves}}} return Manifest{Module: "systemd", Version: "1", Claims: []Claim{{Name: ServiceManagerSeat, Scope: ScopeNode, Serves: serves}}}
+8 -2
View File
@@ -67,12 +67,18 @@ func TestOwnManifestUsesNoWordTheRunningControllerRefuses(t *testing.T) {
} }
for _, want := range []string{"word:tool-runner", "word:core-credentials", "word:bus-state", "word:bus-state.storage", for _, want := range []string{"word:tool-runner", "word:core-credentials", "word:bus-state", "word:bus-state.storage",
// The reference form a registry seat answers (ADR 0605 §9), and the seats the registry milestone adds. // The reference form a registry seat answers (ADR 0605 §9), and the seats the registry milestone adds.
ReadForm + ReferenceFormSeat, ReadForm + ReferenceFormSeatReach, "seat:go-package-registry", "seat:container-image-registry", "seat:oci-artifact-registry"} { ReadForm + ReferenceFormSeat, ReadForm + ReferenceFormSeatReach, "seat:go-package-registry", "seat:container-image-registry", "seat:oci-artifact-registry",
// H-A-388: the declaration Version a node-engine reads and a composer writes, the delivery plan's edge.
"word:declaration-reads", "word:declaration-writes",
// H-A-394: a module's class, core or leaf.
"word:class"} {
if !slices.Contains(added, want) { if !slices.Contains(added, want) {
t.Errorf("%s is in the baseline, or not read: added since it are %v", want, added) t.Errorf("%s is in the baseline, or not read: added since it are %v", want, added)
} }
} }
for _, want := range []string{"word:claims.serves", "word:settings.default", "form:config", "form:setting", "seat:mesh-catalog"} { for _, want := range []string{"word:claims.serves", "word:settings.default", "form:config", "form:setting", "seat:mesh-catalog",
// H-A-383: every node-engine reads a state's max-mib, so a manifest naming it needs no newer engine.
"word:state.max-mib"} {
if !slices.Contains(baseline, want) { if !slices.Contains(baseline, want) {
t.Errorf("the baseline lacks %s", want) t.Errorf("the baseline lacks %s", want)
} }
+30
View File
@@ -2,6 +2,7 @@ package catalogue
import ( import (
"encoding/json" "encoding/json"
"reflect"
"strings" "strings"
"testing" "testing"
@@ -28,6 +29,35 @@ func TestAManifestMaySayWhatStateItKeepsAndReads(t *testing.T) {
if string(out) != `["servers",{"name":"seen","history":5,"ttl-seconds":3600}]` { if string(out) != `["servers",{"name":"seen","history":5,"ttl-seconds":3600}]` {
t.Fatalf("written back as %s", out) t.Fatalf("written back as %s", out)
} }
// Design 47 H2 §812, §814: the validator reads every state, log and objects entry of a manifest that names no cap, in
// the old sections and in requires alike; a capped entry, and an entry of another template, is none of them.
t.Run("each kept store that names no cap", func(t *testing.T) {
m, err := decodeForTest([]byte(`{"module":"x","version":"1",
"state":["seen",{"name":"held","max-mib":8}],
"logs":[{"name":"acts"},{"name":"kept","max-mib":64}],
"objects":[{"name":"outputs","max-mib":256}],
"requires":[{"name":"performed","storage":"key-value","template":"state","options":{"history":1}},
{"name":"taken","storage":"key-value","template":"state","options":{"max-mib":8,"key-ttl":true}},
{"name":"archives","storage":"object-store","template":"objects"},
{"name":"finding-events","storage":"stream","template":"events"}]}`))
if err != nil {
t.Fatal(err)
}
want := []Uncapped{{Name: "seen", Kind: "state", OldSection: true}, {Name: "acts", Kind: "log", OldSection: true},
{Name: "performed", Kind: "state"}, {Name: "archives", Kind: "objects"}}
if got := m.UncappedStores(); !reflect.DeepEqual(got, want) {
t.Fatalf("the uncapped stores are %+v, want %+v", got, want)
}
})
// Design 47 H2 §810 (H-A-394): a manifest says its class, core or leaf; one that names none is a leaf.
t.Run("its class, none a leaf", func(t *testing.T) {
for raw, leaf := range map[string]bool{`"class":"core",`: false, `"class":"leaf",`: true, ``: true} {
m, err := decodeForTest([]byte(`{` + raw + `"module":"x","version":"1"}`))
if err != nil || m.Leaf() != leaf || m.UnknownField() != "" {
t.Errorf("%s read as class %q, leaf %v (%v, unknown %q), want leaf %v", raw, m.Class, m.Leaf(), err, m.UnknownField(), leaf)
}
}
})
} }
// 1154/AC1: a state entry may say key-ttl; it is read, written back, and a bare name or an entry without it reads as before. // 1154/AC1: a state entry may say key-ttl; it is read, written back, and a bare name or an entry without it reads as before.
+17 -4
View File
@@ -26,9 +26,10 @@ import (
"git.novox.be/novox/mesh-sdk/go/seal" "git.novox.be/novox/mesh-sdk/go/seal"
) )
// Version is the vocabulary this host speaks. A declaration naming any other version is // Version is the vocabulary this host speaks, the declaration's form. A declaration naming a higher version is
// refused: an older host handed a newer vocabulary must not quietly do half of it. // refused: an older host handed a newer vocabulary must not quietly do half of it. A lower one is a part of this
const Version = 1 // vocabulary and is read. Version 2 carries a process's drain-bound (design 47 H2 §813 (12), H-A-358, H-A-388).
const Version = 2
// Type names a kind of resource. Every addition widens what a compromised control plane can // Type names a kind of resource. Every addition widens what a compromised control plane can
// express, so the list is a security artefact and grows deliberately. // express, so the list is a security artefact and grows deliberately.
@@ -921,6 +922,11 @@ type Process struct {
// runtime of a build seat's holder, whose builds must never slow the operator's desktop. Absent: the machine's // runtime of a build seat's holder, whose builds must never slow the operator's desktop. Absent: the machine's
// defaults. For a process that stays up. // defaults. For a process that stays up.
Yields *Yields `json:"yields,omitempty"` Yields *Yields `json:"yields,omitempty"`
// DrainBound is how long, in seconds, the process finishes the calls in flight once stopped before it exits
// (design 47 H2 §813 (12); H-A-358): the node-engine writes the unit's stop so the stop signal reaches this process
// alone and waits that long and the time its children take. Absent: none. For a process that stays up.
DrainBound int `json:"drain-bound,omitempty"`
} }
// YieldIdle is the one priority a process yields at: the lowest there is. // YieldIdle is the one priority a process yields at: the lowest there is.
@@ -1024,6 +1030,13 @@ func (d *Process) validate(where string, _ bool) []string {
problems = append(problems, where+": a witness judges a process that stays up; a step or a "+ problems = append(problems, where+": a witness judges a process that stays up; a step or a "+
"scheduled run is not running between its runs") "scheduled run is not running between its runs")
} }
if d.DrainBound < 0 {
problems = append(problems, fmt.Sprintf("%s: drain-bound is %d: a bound is seconds, none or more", where, d.DrainBound))
}
if d.DrainBound > 0 && (d.RunOnce || d.Schedule != "") {
problems = append(problems, where+": drain-bound is for a process that stays up; a step or a scheduled run "+
"is not stopped while it serves calls")
}
if strings.ContainsAny(d.NotReversible, "\n\r") { if strings.ContainsAny(d.NotReversible, "\n\r") {
problems = append(problems, where+": not-reversible is one line") problems = append(problems, where+": not-reversible is one line")
} }
@@ -2349,7 +2362,7 @@ func parse(raw []byte, allowActions bool) (*Declaration, error) {
return nil, &RefusalError{Problems: []string{"not a declaration: " + err.Error()}} return nil, &RefusalError{Problems: []string{"not a declaration: " + err.Error()}}
} }
if env.Version != Version { if env.Version < 1 || env.Version > Version {
// Everything below assumes the vocabulary, so there is nothing further to say. // Everything below assumes the vocabulary, so there is nothing further to say.
return nil, &RefusalError{Problems: []string{fmt.Sprintf( return nil, &RefusalError{Problems: []string{fmt.Sprintf(
"declaration version %d; this host speaks version %d. Refused whole rather than "+ "declaration version %d; this host speaks version %d. Refused whole rather than "+
+15 -1
View File
@@ -2,6 +2,7 @@ package declaration
import ( import (
"errors" "errors"
"fmt"
"strings" "strings"
"testing" "testing"
) )
@@ -92,9 +93,22 @@ func testAnUnknownVersionIsRefusedWhole(t *testing.T) {
{"id":"a","type":"directory","path":"/etc/mesh"} {"id":"a","type":"directory","path":"/etc/mesh"}
]}`) ]}`)
joined := strings.Join(refusal.Problems, "\n") joined := strings.Join(refusal.Problems, "\n")
if !strings.Contains(joined, "99") || !strings.Contains(joined, "version 1") { if !strings.Contains(joined, "99") || !strings.Contains(joined, "version 2") {
t.Errorf("the version mismatch was not stated plainly: %v", refusal.Problems) t.Errorf("the version mismatch was not stated plainly: %v", refusal.Problems)
} }
// Design 47 H2 §813 (12), H-A-388: Version is the declaration's form, raised to 2 by drain-bound; a lower one is a
// part of this vocabulary and is read, so a node-engine that reads 2 takes what a composer of 1 still writes.
for _, v := range []int{1, Version} {
if _, err := Parse([]byte(fmt.Sprintf(`{"declaration":%d,"resources":[{"id":"a","type":"directory","path":"/etc/mesh"}]}`, v))); err != nil {
t.Errorf("a declaration of version %d was refused: %v", v, err)
}
}
if Version != 2 {
t.Errorf("the declaration's Version is %d, want 2 (H-A-388)", Version)
}
if r := refusalFor(t, `{"declaration":0,"resources":[]}`); !strings.Contains(strings.Join(r.Problems, " "), "version 0") {
t.Errorf("a declaration of version 0 was refused as %v", r.Problems)
}
// Nothing else is reported, because everything else assumes a vocabulary this host does // Nothing else is reported, because everything else assumes a vocabulary this host does
// not have — a list of complaints derived from the wrong grammar is noise. // not have — a list of complaints derived from the wrong grammar is noise.
if len(refusal.Problems) != 1 { if len(refusal.Problems) != 1 {
+16
View File
@@ -1,6 +1,7 @@
package declaration package declaration
import ( import (
"encoding/json"
"strings" "strings"
"testing" "testing"
) )
@@ -99,6 +100,9 @@ func testTheModesAreExclusive(t *testing.T) {
"an unknown priority": func(p *Process) { p.Yields = &Yields{Priority: "low"} }, "an unknown priority": func(p *Process) { p.Yields = &Yields{Priority: "low"} },
"a share over the whole": func(p *Process) { p.Yields = &Yields{CPUShare: 150} }, "a share over the whole": func(p *Process) { p.Yields = &Yields{CPUShare: 150} },
"a yield saying nothing": func(p *Process) { p.Yields = &Yields{} }, "a yield saying nothing": func(p *Process) { p.Yields = &Yields{} },
// Design 47 H2 §813 (12), H-A-358: a drain bound is seconds, for a process that stays up.
"a step with a drain bound": func(p *Process) { p.RunOnce = true; p.DrainBound = 30 },
"a negative drain bound": func(p *Process) { p.DrainBound = -1 },
} { } {
p := aProcess() p := aProcess()
bad(p) bad(p)
@@ -106,6 +110,18 @@ func testTheModesAreExclusive(t *testing.T) {
t.Errorf("%s was accepted", name) t.Errorf("%s was accepted", name)
} }
} }
// It travels in the declaration under drain-bound, and so in its digest; absent says none.
up := aProcess()
up.DrainBound = 30
if problems := up.validate("a process", false); len(problems) != 0 {
t.Errorf("a process that stays up with a drain bound was refused: %v", problems)
}
if b, _ := json.Marshal(up); !strings.Contains(string(b), `"drain-bound":30`) {
t.Errorf("the drain bound is not in the declaration: %s", b)
}
if b, _ := json.Marshal(aProcess()); strings.Contains(string(b), "drain-bound") {
t.Errorf("a process with no drain bound says one: %s", b)
}
} }
// A cadence that is not a cadence is refused near its author, rather than by a machine at the far // A cadence that is not a cadence is refused near its author, rather than by a machine at the far
+1 -1
View File
@@ -6,6 +6,7 @@ require (
github.com/klauspost/compress v1.20.0 github.com/klauspost/compress v1.20.0
github.com/nats-io/nats-server/v2 v2.11.17 github.com/nats-io/nats-server/v2 v2.11.17
github.com/nats-io/nats.go v1.54.0 github.com/nats-io/nats.go v1.54.0
golang.org/x/crypto v0.57.0
) )
require ( require (
@@ -15,7 +16,6 @@ require (
github.com/nats-io/jwt/v2 v2.8.1 // indirect github.com/nats-io/jwt/v2 v2.8.1 // indirect
github.com/nats-io/nkeys v0.4.16 // indirect github.com/nats-io/nkeys v0.4.16 // indirect
github.com/nats-io/nuid v1.0.1 // indirect github.com/nats-io/nuid v1.0.1 // indirect
golang.org/x/crypto v0.57.0 // indirect
golang.org/x/sys v0.48.0 // indirect golang.org/x/sys v0.48.0 // indirect
golang.org/x/time v0.15.0 // indirect golang.org/x/time v0.15.0 // indirect
) )
+9
View File
@@ -14,6 +14,9 @@ import (
"github.com/nats-io/nats.go" "github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream" "github.com/nats-io/nats.go/jetstream"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/busretry"
) )
// 1171/AC2: given an account file broker-<process id> in the controller's form {url, fingerprint, node, // 1171/AC2: given an account file broker-<process id> in the controller's form {url, fingerprint, node,
@@ -342,6 +345,12 @@ func subTheOwnBuildIsTheFingerprintTheProcessWasStartedWith(t *testing.T) {
t.Errorf("%s: the process's own build is not said at its start: %+v", name, said) t.Errorf("%s: the process's own build is not said at its start: %+v", name, said)
} }
} }
// Design 47 H2 §775, §781: Connect reads the module's kept-call pace from its settings, and refuses one that is no
// duration, naming it.
t.Setenv(stdio.SettingWord(busretry.PaceFirstSetting), "soon")
if _, err := Connect(Account{URL: "nats://127.0.0.1:1", User: "n1.m"}); err == nil || !strings.Contains(err.Error(), "kept-call-pace-first") {
t.Errorf("a pace that is no duration connected: %v", err)
}
} }
// TestReadAccountYieldsEveryFieldAndToleratesClaims runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest. // TestReadAccountYieldsEveryFieldAndToleratesClaims runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
+76 -26
View File
@@ -10,6 +10,7 @@ import (
"github.com/nats-io/nats.go" "github.com/nats-io/nats.go"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/approval" "git.novox.be/novox/mesh-sdk/go/approval"
"git.novox.be/novox/mesh-sdk/go/busretry" "git.novox.be/novox/mesh-sdk/go/busretry"
"git.novox.be/novox/mesh-sdk/go/calladdress" "git.novox.be/novox/mesh-sdk/go/calladdress"
@@ -52,34 +53,51 @@ func (c *Conn) CallOn(node, key string, body any) (json.RawMessage, error) {
} }
// CallKept is Call for a call whose answer the caller keeps and which is safe to make again (a read, or a write the // CallKept is Call for a call whose answer the caller keeps and which is safe to make again (a read, or a write the
// callee deduplicates): it is asked again through a transport fault, a timeout or no responders, whether or not the bus // callee deduplicates): mesh-sdk's kept-call form (design 47 H2 §775), asked again through a transport fault, a timeout
// is blacked out, until it is answered or busretry.Bound has passed (novox/hq ADR 0668, extending ADR 0615 §6; issue // or no responders at the kept-call pace (busretry.KeptPace(), jittered), whether or not the bus is blacked out, until it
// 1966). A callee that restarts answers no one for seconds; Call fails that at once. The caller keeps a call still // is answered or busretry.Bound has passed (novox/hq ADR 0668, extending ADR 0615 §6; issue 1966). A refusal returns at
// unanswered past the bound as a wait of its own, and makes it again on the callee's event or its consumer's bind. // once. A caller with an ask id and a bound of its own uses CallKeptAsk.
func (c *Conn) CallKept(key string, body any) (json.RawMessage, error) { func (c *Conn) CallKept(key string, body any) (json.RawMessage, error) {
called, fallback, err := callSubjectsOn(key, "", c.callerToken()) return c.CallKeptAsk(KeptAsk{}, key, body)
if err != nil {
return nil, err
}
return c.callKeptOn(called, fallback, body)
} }
// CallKeptOn is CallKept to the tool or seat verb of one named machine, as CallOn is Call's. // CallKeptOn is CallKept to the tool or seat verb of one named machine, as CallOn is Call's.
func (c *Conn) CallKeptOn(node, key string, body any) (json.RawMessage, error) { func (c *Conn) CallKeptOn(node, key string, body any) (json.RawMessage, error) {
return c.CallKeptAskOn(KeptAsk{}, node, key, body)
}
// KeptAsk is what a caller names of its kept call (design 47 H2 §775): the ask's id, which the call carries in the
// header stdio.AskHeader for the holder to take it once by (H-A-351), and the caller's bound (zero is busretry.Bound).
type KeptAsk struct {
ID string
Bound time.Duration
}
// CallKeptAsk is CallKept carrying ask's id and stopping at ask's bound: past it the error is a *busretry.Unanswered
// naming every call's time and words.
func (c *Conn) CallKeptAsk(ask KeptAsk, key string, body any) (json.RawMessage, error) {
return c.callKeptAskOn(ask, "", key, body, nil)
}
// CallKeptAskOn is CallKeptAsk to the tool or seat verb of one named machine.
func (c *Conn) CallKeptAskOn(ask KeptAsk, node, key string, body any) (json.RawMessage, error) {
if err := calladdress.CheckNode(node); err != nil { if err := calladdress.CheckNode(node); err != nil {
return nil, err return nil, err
} }
called, fallback, err := callSubjectsOn(key, node, c.callerToken()) return c.callKeptAskOn(ask, node, key, body, nil)
if err != nil {
return nil, err
}
return c.callKeptOn(called, fallback, body)
} }
// CallKeptWhileOpen is CallKept for an ask the asker can close or replace: it is asked again only while open says its // CallKeptWhileOpen is CallKept for an ask the asker can close or replace: it is asked again only while open says its
// key is still open (design 47 G §351, §460). // key is still open (design 47 G §351, §460).
func (c *Conn) CallKeptWhileOpen(open busretry.Open, key string, body any) (json.RawMessage, error) { func (c *Conn) CallKeptWhileOpen(open busretry.Open, key string, body any) (json.RawMessage, error) {
called, fallback, err := callSubjectsOn(key, "", c.callerToken()) if open.Open == nil {
return nil, fmt.Errorf("the call on %s: a kept call names its key's open function", key)
}
return c.callKeptAskOn(KeptAsk{}, "", key, body, &open)
}
func (c *Conn) callKeptAskOn(ask KeptAsk, node, key string, body any, open *busretry.Open) (json.RawMessage, error) {
called, fallback, err := callSubjectsOn(key, node, c.callerToken())
if err != nil { if err != nil {
return nil, err return nil, err
} }
@@ -87,21 +105,35 @@ func (c *Conn) CallKeptWhileOpen(open busretry.Open, key string, body any) (json
if err != nil { if err != nil {
return nil, err return nil, err
} }
return busretry.DoKept("the call on "+fallback, open, askBoth(c.request, called, fallback, data), nil) return callKeptWith(keptOf(key, ask, open), c.requestAsking(ask.ID), called, fallback, data)
} }
func (c *Conn) callKeptOn(called, fallback string, body any) (json.RawMessage, error) { // keptOf is the paced form's naming of a call on key: its seat and verb, or its module and tool.
data, err := json.Marshal(body) func keptOf(key string, ask KeptAsk, open *busretry.Open) busretry.Kept {
if err != nil { k := busretry.Kept{Ask: ask.ID, Bound: ask.Bound, Open: open}
return nil, err if a, err := calladdress.Parse(key); err == nil {
k.Seat, k.Verb = a.Seat, a.Verb
if a.Seat == "" {
k.Seat, k.Verb = a.Module, a.Tool
}
} }
return callKeptWith(c.request, called, fallback, data) return k
} }
// callKeptWith is callWith for a kept call: busretry.DoRepeatable with no blackout probe. // callKeptWith is callWith for a kept call: busretry.DoPaced with no blackout probe.
func callKeptWith(request func(string, []byte) (json.RawMessage, error), called, fallback string, func callKeptWith(k busretry.Kept, request func(string, []byte) (json.RawMessage, error), called, fallback string,
data []byte) (json.RawMessage, error) { data []byte) (json.RawMessage, error) {
return busretry.DoRepeatable("the call on "+fallback, askBoth(request, called, fallback, data), nil) ask := askBoth(request, called, fallback, data)
return busretry.DoPaced(k, func() (json.RawMessage, error) {
result, err := ask()
if err == nil {
// A holder's answer of the kind away is a transport fault (§776): called again at the pace.
if away := busretry.AwayIn(result); away != nil {
return result, away
}
}
return result, err
})
} }
// askBoth asks called, then fallback when nothing answers it. // askBoth asks called, then fallback when nothing answers it.
@@ -209,10 +241,28 @@ func callSubjectsOn(key, node, token string) (called, fallback string, err error
// request asks one subject once and reads its reply ({result, error, node}); a reply naming an error is // request asks one subject once and reads its reply ({result, error, node}); a reply naming an error is
// the call's failure, not a transport one. // the call's failure, not a transport one.
func (c *Conn) request(subject string, data []byte) (json.RawMessage, error) { func (c *Conn) request(subject string, data []byte) (json.RawMessage, error) {
ctx, cancel := context.WithTimeout(context.Background(), CallTimeout) return c.requestAsk(subject, data, "")
defer cancel() }
// requestAsking is request carrying an ask's id in the header stdio.AskHeader (H-A-351); empty carries none.
func (c *Conn) requestAsking(ask string) func(string, []byte) (json.RawMessage, error) {
return func(subject string, data []byte) (json.RawMessage, error) { return c.requestAsk(subject, data, ask) }
}
// askMsg is the request a call publishes: its ask's id in stdio.AskHeader when it carries one (H-A-351).
func askMsg(subject string, data []byte, ask string) *nats.Msg {
req := nats.NewMsg(subject) req := nats.NewMsg(subject)
req.Data = data req.Data = data
if ask != "" {
req.Header.Set(stdio.AskHeader, ask)
}
return req
}
func (c *Conn) requestAsk(subject string, data []byte, ask string) (json.RawMessage, error) {
ctx, cancel := context.WithTimeout(context.Background(), CallTimeout)
defer cancel()
req := askMsg(subject, data, ask)
if strings.HasPrefix(subject, "mesh.seat.") { if strings.HasPrefix(subject, "mesh.seat.") {
// Every seat call says it waits for a held call's end; a verb that is not marked ignores it (lead answer A-244). // Every seat call says it waits for a held call's end; a verb that is not marked ignores it (lead answer A-244).
req.Header.Set(approval.WaitHeader, approval.WaitHeld) req.Header.Set(approval.WaitHeader, approval.WaitHeld)
+107 -1
View File
@@ -1,8 +1,11 @@
package process package process
import ( import (
"bytes"
"context" "context"
"encoding/json" "encoding/json"
"errors"
"fmt"
"git.novox.be/novox/mesh-sdk/go/seatdef" "git.novox.be/novox/mesh-sdk/go/seatdef"
"strings" "strings"
"testing" "testing"
@@ -10,6 +13,9 @@ import (
"github.com/nats-io/nats.go" "github.com/nats-io/nats.go"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/approval"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/busretry" "git.novox.be/novox/mesh-sdk/go/busretry"
) )
@@ -128,7 +134,7 @@ func TestACallIsAskedAgainOnlyWhenItReachedNoOne(t *testing.T) {
} }
var err error var err error
if row.kept { if row.kept {
_, err = callKeptWith(request, "called", "fallback", nil) _, err = callKeptWith(busretry.Kept{Seat: "s", Verb: "v"}, request, "called", "fallback", nil)
} else { } else {
_, err = callWith(request, func() bool { return true }, "called", "fallback", nil) _, err = callWith(request, func() bool { return true }, "called", "fallback", nil)
} }
@@ -136,6 +142,106 @@ func TestACallIsAskedAgainOnlyWhenItReachedNoOne(t *testing.T) {
t.Errorf("%s: asked %d times (%v), want %d", row.name, asks, err, row.asks) t.Errorf("%s: asked %d times (%v), want %d", row.name, asks, err, row.asks)
} }
} }
// Design 47 H2 §776: a holder's answer of the kind away is a transport fault, called again at the pace; a refusal
// of another kind is the caller's answer at once.
for _, row := range []struct {
name string
answers []string
asks int
}{
{"away, then answered", []string{`{"error":"x","error-kind":"away","part":"the forge's store","words":"401"}`, `{"merged":true}`}, 2},
{"refused: answered at once", []string{`{"error":"no","error-kind":"refused"}`}, 1},
} {
asks := 0
request := func(string, []byte) (json.RawMessage, error) {
a := row.answers[min(asks, len(row.answers)-1)]
asks++
return json.RawMessage(a), nil
}
got, err := callKeptWith(busretry.Kept{Seat: "git", Verb: "merge-pull"}, request, "called", "fallback", nil)
if asks != row.asks || err != nil || string(got) != row.answers[len(row.answers)-1] {
t.Errorf("%s: asked %d times, %s, %v", row.name, asks, got, err)
}
}
// Design 47 H2 §775, H-A-351: a kept call carries its ask's id in the header, and a holder in a process reads it with
// AskOf while its handler runs; a call carrying none reads empty.
if m := askMsg("mesh.seat.mesh-builds.call.build", []byte(`{}`), "ask-9"); m.Header.Get(stdio.AskHeader) != "ask-9" {
t.Errorf("the ask's id is not in the header: %v", m.Header)
}
if m := askMsg("s", nil, ""); m.Header.Get(stdio.AskHeader) != "" {
t.Errorf("a call with no ask carries one: %v", m.Header)
}
c := &Conn{}
for _, ask := range []string{"ask-9", ""} {
msg := askMsg("mesh.seat.mesh-builds.tool.build", []byte(`{"x":1}`), ask)
read := "unread"
c.answerCall(msg, "mesh.seat.mesh-builds.tool.build", func(_ string, body json.RawMessage, _ bool) (any, *approval.Held, error) {
read = AskOf(body)
return nil, nil, nil
})
if read != ask || AskOf(json.RawMessage(msg.Data)) != "" {
t.Errorf("the holder read the ask %q, want %q, and none once its handler ended", read, ask)
}
}
// Design 47 H2 §775, H-A-405: a kept chunked call (CallChunksKept, CallFileKept) asks its verb through the kept-call
// form, carries its one ask id on every chunk's acknowledgement, and past its bound ends with the kept call's words.
send := buscalls.SeatChunks{Seat: "node-build-go", Verb: "output", Call: "c1"}
for _, row := range []struct {
name string
answer []error // per ask; the last repeats
bound time.Duration
asks int
chunks int64
unasked bool // ends unanswered past its bound
}{
{"no responders twice, then answered with two chunks", []error{nats.ErrNoResponders, nats.ErrNoResponders, nil}, 0, 3, 2, false},
{"answered at once with three chunks", []error{nil}, 0, 1, 3, false},
{"no responders past its bound", []error{nats.ErrNoResponders}, time.Nanosecond, 2, 0, true},
} {
asks := 0
request := func(string, []byte) (json.RawMessage, error) {
e := row.answer[min(asks, len(row.answer)-1)]
asks++
return json.RawMessage(fmt.Sprintf(`{"chunks":%d}`, row.chunks)), e
}
chunks := make(chan *nats.Msg, row.chunks)
var want bytes.Buffer
for n := int64(1); n <= row.chunks; n++ {
data := []byte(fmt.Sprintf("part %d;", n))
want.Write(data)
body, _ := json.Marshal(buscalls.SeatChunk{N: n, Of: row.chunks, Data: data})
chunks <- &nats.Msg{Subject: send.Chunk(n), Data: body}
}
var acks []string
ack := func(m *nats.Msg) error {
acks = append(acks, m.Subject+" "+m.Header.Get(stdio.AskHeader))
return nil
}
ask := KeptAsk{ID: "ask-7", Bound: row.bound}
asking := func() (json.RawMessage, error) {
return callKeptWith(keptOf("seat:node-build-go.output@ace", ask, nil), request, "called", "fallback", nil)
}
var got bytes.Buffer
_, err := receiveChunks(context.Background(), "seat:node-build-go.output@ace", send, chunks, ask.ID, asking, nil, ack, &got)
var unanswered *busretry.Unanswered
if row.unasked != errors.As(err, &unanswered) || asks != row.asks || (!row.unasked && err != nil) {
t.Errorf("%s: asked %d times (want %d), %v", row.name, asks, row.asks, err)
}
if row.unasked && (unanswered.Ask != "ask-7" || !strings.Contains(err.Error(), "node-build-go.output (ask ask-7) unanswered within its bound")) {
t.Errorf("%s: ended with %v, not the kept call's words", row.name, err)
}
if got.String() != want.String() || int64(len(acks)) != row.chunks {
t.Errorf("%s: received %q and acknowledged %d chunks, want %q and %d", row.name, got.String(), len(acks), want.String(), row.chunks)
}
for n, a := range acks {
if a != send.Ack(int64(n+1))+" ask-7" {
t.Errorf("%s: acknowledgement %d is %q, carrying not the ask's id in its header", row.name, n+1, a)
}
}
}
if _, err := (&Conn{}).CallChunksKept(context.Background(), KeptAsk{}, "seat:node-build-go.output", "c1", nil, nil, &bytes.Buffer{}); err == nil {
t.Error("a kept chunked call naming no ask id was made")
}
} }
// A-107: AnswerSeat reads the caller from a call's last token (dots written `~`), "" for anything that is not a // A-107: AnswerSeat reads the caller from a call's last token (dots written `~`), "" for anything that is not a
+80 -16
View File
@@ -22,24 +22,77 @@ import (
// is taken), then receives the number of chunks the answer's member `chunks` names, in order, acknowledging each, into w. // is taken), then receives the number of chunks the answer's member `chunks` names, in order, acknowledging each, into w.
// It answers the verb's answer. A chunk that does not come within buscalls.SeatAckWithin, or ctx ending, ends the receive. // It answers the verb's answer. A chunk that does not come within buscalls.SeatAckWithin, or ctx ending, ends the receive.
func (c *Conn) CallChunks(ctx context.Context, key, call string, body any, accept func(answer json.RawMessage) error, w io.Writer) (json.RawMessage, error) { func (c *Conn) CallChunks(ctx context.Context, key, call string, body any, accept func(answer json.RawMessage) error, w io.Writer) (json.RawMessage, error) {
a, err := calladdress.Parse(key) return c.callChunks(ctx, key, call, "", func() (json.RawMessage, error) { return c.Call(key, body) }, accept, w)
}
// CallChunksKept is CallChunks made as a kept call (design 47 H2 §775; H-A-405): the verb is asked through the kept-call
// form (busretry.DoPaced: called again at the kept-call pace on a transport fault, ADR 0664 §1's classes, the call's own
// deadline and the kind away; one journal line per seat at the first fault, then at most once a minute), carrying ask's id
// in the header stdio.AskHeader on the call and on every chunk's acknowledgement, and stopping at ask's bound with the
// words CallKeptAsk gives (a *busretry.Unanswered naming every call). A kept chunked call carries an ask id: one naming
// none is refused before anything is published.
func (c *Conn) CallChunksKept(ctx context.Context, ask KeptAsk, key, call string, body any, accept func(answer json.RawMessage) error,
w io.Writer) (json.RawMessage, error) {
if ask.ID == "" {
return nil, fmt.Errorf("the kept call of %s names no ask id", key)
}
called, fallback, err := callSubjectsOn(key, "", c.callerToken())
if err != nil { if err != nil {
return nil, err return nil, err
} }
if a.Seat == "" { data, err := json.Marshal(body)
return nil, fmt.Errorf("%q names no seat verb, so it sends no chunks", key) if err != nil {
return nil, err
} }
if call == "" { asking := func() (json.RawMessage, error) {
return nil, fmt.Errorf("the call of %s names no call token for its chunks", key) return callKeptWith(keptOf(key, ask, nil), c.requestAsking(ask.ID), called, fallback, data)
}
return c.callChunks(ctx, key, call, ask.ID, asking, accept, w)
}
// callChunks hears the chunks of call before it asks through asking, then receives them (receiveChunks), acknowledging
// each with ask's id in stdio.AskHeader when it carries one.
func (c *Conn) callChunks(ctx context.Context, key, call, ask string, asking func() (json.RawMessage, error),
accept func(answer json.RawMessage) error, w io.Writer) (json.RawMessage, error) {
send, err := chunksOf(key, call)
if err != nil {
return nil, err
} }
send := buscalls.SeatChunks{Seat: a.Seat, Verb: a.Verb, Call: call}
chunks := make(chan *nats.Msg, 4) chunks := make(chan *nats.Msg, 4)
sub, err := c.nc.ChanSubscribe(send.Chunks(), chunks) sub, err := c.nc.ChanSubscribe(send.Chunks(), chunks)
if err != nil { if err != nil {
return nil, fmt.Errorf("the chunks of %s cannot be heard: %w", key, err) return nil, fmt.Errorf("the chunks of %s cannot be heard: %w", key, err)
} }
defer func() { _ = sub.Unsubscribe() }() defer func() { _ = sub.Unsubscribe() }()
answer, err := c.Call(key, body) ack := func(m *nats.Msg) error {
_, err := c.nc.RequestMsg(m, buscalls.SeatAckWithin)
return err
}
return receiveChunks(ctx, key, send, chunks, ask, asking, accept, ack, w)
}
// chunksOf is the chunks of call of the seat verb key names; a key naming no seat verb, or no call, is refused.
func chunksOf(key, call string) (buscalls.SeatChunks, error) {
a, err := calladdress.Parse(key)
if err != nil {
return buscalls.SeatChunks{}, err
}
if a.Seat == "" {
return buscalls.SeatChunks{}, fmt.Errorf("%q names no seat verb, so it sends no chunks", key)
}
if call == "" {
return buscalls.SeatChunks{}, fmt.Errorf("the call of %s names no call token for its chunks", key)
}
return buscalls.SeatChunks{Seat: a.Seat, Verb: a.Verb, Call: call}, nil
}
// receiveChunks asks through asking, hands its answer to accept, then receives the number of chunks the answer's member
// `chunks` names from chunks, in order, acknowledging each through ack with a message carrying ask's id in
// stdio.AskHeader (none when empty), into w.
func receiveChunks(ctx context.Context, key string, send buscalls.SeatChunks, chunks <-chan *nats.Msg, ask string,
asking func() (json.RawMessage, error), accept func(answer json.RawMessage) error, ack func(*nats.Msg) error,
w io.Writer) (json.RawMessage, error) {
answer, err := asking()
if err != nil { if err != nil {
return nil, err return nil, err
} }
@@ -66,11 +119,8 @@ func (c *Conn) CallChunks(ctx context.Context, key, call string, body any, accep
return "", nil, ctx.Err() return "", nil, ctx.Err()
} }
} }
ack := func(subject string) error { acked := func(subject string) error { return ack(askMsg(subject, []byte("{}"), ask)) }
_, err := c.nc.Request(subject, []byte("{}"), buscalls.SeatAckWithin) if _, err := send.Receive(count.Chunks, next, acked, w); err != nil {
return err
}
if _, err := send.Receive(count.Chunks, next, ack, w); err != nil {
return answer, fmt.Errorf("the answer of %s: %w", key, err) return answer, fmt.Errorf("the answer of %s: %w", key, err)
} }
return answer, nil return answer, nil
@@ -80,18 +130,32 @@ func (c *Conn) CallChunks(ctx context.Context, key, call string, body any, accep
// G A-249, A-253): the verb's answer with the whole file added as its member `file` (base64), none when no chunk was sent. The // G A-249, A-253): the verb's answer with the whole file added as its member `file` (base64), none when no chunk was sent. The
// call token is body's member `call`. // call token is body's member `call`.
func (c *Conn) CallFile(key string, body any) (json.RawMessage, error) { func (c *Conn) CallFile(key string, body any) (json.RawMessage, error) {
call := callOf(body)
var file bytes.Buffer var file bytes.Buffer
answer, err := c.CallChunks(context.Background(), key, call, body, nil, &file) answer, err := c.CallChunks(context.Background(), key, callOf(body), body, nil, &file)
if err != nil { if err != nil {
return nil, err return nil, err
} }
return withFile(key, answer, file.Bytes())
}
// CallFileKept is CallFile made as a kept call, as CallChunksKept is CallChunks's (design 47 H2 §775; H-A-405).
func (c *Conn) CallFileKept(ask KeptAsk, key string, body any) (json.RawMessage, error) {
var file bytes.Buffer
answer, err := c.CallChunksKept(context.Background(), ask, key, callOf(body), body, nil, &file)
if err != nil {
return nil, err
}
return withFile(key, answer, file.Bytes())
}
// withFile is a chunked verb's answer with file added as its member `file` (base64), none when file is empty.
func withFile(key string, answer json.RawMessage, file []byte) (json.RawMessage, error) {
var whole map[string]any var whole map[string]any
if err := json.Unmarshal(answer, &whole); err != nil { if err := json.Unmarshal(answer, &whole); err != nil {
return nil, fmt.Errorf("%s answered what is no object: %w", key, err) return nil, fmt.Errorf("%s answered what is no object: %w", key, err)
} }
if file.Len() > 0 { if len(file) > 0 {
whole["file"] = base64.StdEncoding.EncodeToString(file.Bytes()) whole["file"] = base64.StdEncoding.EncodeToString(file)
} }
return json.Marshal(whole) return json.Marshal(whole)
} }
+6
View File
@@ -12,6 +12,9 @@ import (
"sync" "sync"
"github.com/nats-io/nats.go" "github.com/nats-io/nats.go"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/busretry"
) )
// Conn is one process's own connection to the bus (novox/hq ADR 0436 clause 4): dialled with the account // Conn is one process's own connection to the bus (novox/hq ADR 0436 clause 4): dialled with the account
@@ -54,6 +57,9 @@ var refusedPublish = regexp.MustCompile(`(?i)Publish to "(\S+)"`)
// at once. // at once.
func Connect(account Account, opts ...nats.Option) (*Conn, error) { func Connect(account Account, opts ...nats.Option) (*Conn, error) {
OwnBuild() OwnBuild()
if err := busretry.ReadPace(stdio.SettingDuration); err != nil {
return nil, fmt.Errorf("the kept-call pace of the process account %s: %w", account.User, err)
}
c := &Conn{account: account, pending: map[string]map[uint64]context.CancelCauseFunc{}} c := &Conn{account: account, pending: map[string]map[uint64]context.CancelCauseFunc{}}
nc, err := nats.Connect(account.URL, c.options(opts)...) nc, err := nats.Connect(account.URL, c.options(opts)...)
if err != nil { if err != nil {
+137
View File
@@ -0,0 +1,137 @@
package process
import (
"context"
"encoding/json"
"errors"
"log"
"time"
"github.com/nats-io/nats.go/jetstream"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// sayPrune writes a prune's one journal line (design 47 H2 §812).
var sayPrune = func(line string) { log.Print(line) }
// PrunedState is a state a process prunes at its own writes (design 47 H2 §812; H-A-380): the entry's figures are read
// once when it is bound and once after each prune, and between those a running sum of the bytes each write puts
// (stdio.PutBytes, an upper bound) is the judgement; past prune-mark of the cap the oldest keys by their current
// revision are purged down to prune-target, skipping a key kept under stdio.KeepKey. No read per write, no poll, no timer.
// Its reads are the state's own.
type PrunedState struct {
State
pruner *stdio.Pruner
}
// Pruned binds the state for a prune by p, reading its figures once.
func (s State) Pruned(p stdio.Prune) (*PrunedState, error) {
ps := &PrunedState{State: s}
ps.pruner = &stdio.Pruner{State: s.Module + "'s " + s.Name, Prune: p, Say: func(line string) { sayPrune(line) },
Figures: s.figures, Entries: s.entries, Remove: s.purge}
if err := ps.pruner.Bind(); err != nil {
return nil, err
}
return ps, nil
}
// figures is the bucket's bytes and its cap, zero for none.
func (s State) figures() (uint64, uint64, error) {
ctx, cancel := context.WithTimeout(context.Background(), stateTimeout)
defer cancel()
kv, err := s.store(ctx)
if err != nil {
return 0, 0, err
}
st, err := kv.Status(ctx)
if err != nil {
return 0, 0, err
}
return st.Bytes(), uint64(max(st.Config().MaxBytes, 0)), nil
}
// entries is every current value of the bucket with its revision, keeps included, read once.
func (s State) entries() ([]stdio.PruneEntry, error) {
ctx, cancel := context.WithTimeout(context.Background(), stateTimeout)
defer cancel()
kv, err := s.store(ctx)
if err != nil {
return nil, err
}
w, err := kv.WatchAll(ctx, jetstream.IgnoreDeletes())
if err != nil {
return nil, err
}
defer w.Stop()
var out []stdio.PruneEntry
for {
select {
case e, open := <-w.Updates():
if !open {
return nil, errors.New("the read of the current values ended")
}
if e == nil {
return out, nil
}
if e.Operation() == jetstream.KeyValuePut {
out = append(out, stdio.PruneEntry{Key: e.Key(), Revision: e.Revision(), Bytes: stdio.PutBytes(e.Key(), e.Value()), Value: e.Value()})
}
case <-ctx.Done():
return nil, ctx.Err()
}
}
}
// purge removes a key with its past values, so its bytes leave the bucket.
func (s State) purge(key string) error {
ctx, cancel := context.WithTimeout(context.Background(), stateTimeout)
defer cancel()
kv, err := s.store(ctx)
if err != nil {
return err
}
return kv.Purge(ctx, key)
}
// wrote counts a write and prunes past the mark.
func (s *PrunedState) wrote(key string, value any, rev uint64, err error) (uint64, error) {
if err != nil {
return rev, err
}
data, _ := json.Marshal(value)
if _, err := s.pruner.Wrote(stdio.PutBytes(key, data)); err != nil {
return rev, err
}
return rev, nil
}
// Put writes a key whole, counted toward the prune.
func (s *PrunedState) Put(key string, value any) (uint64, error) {
rev, err := s.State.Put(key, value)
return s.wrote(key, value, rev, err)
}
// Create writes a key only when it has none, counted toward the prune.
func (s *PrunedState) Create(key string, value any) (uint64, error) {
rev, err := s.State.Create(key, value)
return s.wrote(key, value, rev, err)
}
// Update writes a key only when it is still at revision, counted toward the prune.
func (s *PrunedState) Update(key string, value any, revision uint64) (uint64, error) {
rev, err := s.State.Update(key, value, revision)
return s.wrote(key, value, rev, err)
}
// PruneNow prunes the state to its target now.
func (s *PrunedState) PruneNow() (stdio.Pruned, error) { return s.pruner.PruneNow() }
// Keep keeps key from the prune until until, written under stdio.KeepKey.
func (s *PrunedState) Keep(key string, until time.Time) error {
if err := stdio.KeepProblem(key, until); err != nil {
return err
}
_, err := s.Put(stdio.KeepKey(key), stdio.Keep{Until: until.UTC()})
return err
}
+62
View File
@@ -0,0 +1,62 @@
package process
import (
"context"
"github.com/nats-io/nats.go/jetstream"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// pruneKV is a fakeKV with a cap: its bytes are what its current values put (stdio.PutBytes), its Status says them
// with the cap, WatchAll hands every current value, and Purge removes a key.
type pruneKV struct {
*fakeKV
cap int64
statuss int
}
type pruneStatus struct {
jetstream.KeyValueStatus
bytes uint64
cap int64
}
func (s pruneStatus) Bytes() uint64 { return s.bytes }
func (s pruneStatus) Config() jetstream.KeyValueConfig {
return jetstream.KeyValueConfig{MaxBytes: s.cap}
}
func (f *pruneKV) held() uint64 {
f.mu.Lock()
defer f.mu.Unlock()
var n uint64
for k, v := range f.values {
n += stdio.PutBytes(k, v)
}
return n
}
func (f *pruneKV) Status(context.Context) (jetstream.KeyValueStatus, error) {
f.statuss++
return pruneStatus{bytes: f.held(), cap: f.cap}, nil
}
func (f *pruneKV) WatchAll(context.Context, ...jetstream.WatchOpt) (jetstream.KeyWatcher, error) {
f.mu.Lock()
defer f.mu.Unlock()
w := &fakeWatcher{updates: make(chan jetstream.KeyValueEntry, len(f.values)+1)}
for k, v := range f.values {
w.updates <- putEntry{fakeEntry{key: k, value: v, rev: f.revs[k]}}
}
w.updates <- nil
return w, nil
}
func (f *pruneKV) Purge(ctx context.Context, key string, _ ...jetstream.KVDeleteOpt) error {
return f.Delete(ctx, key)
}
type putEntry struct{ fakeEntry }
func (putEntry) Operation() jetstream.KeyValueOp { return jetstream.KeyValuePut }
+25 -1
View File
@@ -6,9 +6,12 @@ import (
"regexp" "regexp"
"sort" "sort"
"strings" "strings"
"sync"
"unsafe"
"github.com/nats-io/nats.go" "github.com/nats-io/nats.go"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/approval" "git.novox.be/novox/mesh-sdk/go/approval"
"git.novox.be/novox/mesh-sdk/go/calladdress" "git.novox.be/novox/mesh-sdk/go/calladdress"
"git.novox.be/novox/mesh-sdk/go/seatdef" "git.novox.be/novox/mesh-sdk/go/seatdef"
@@ -157,6 +160,21 @@ func (c *Conn) admitted(seat, verb string, definition func() (seatdef.Definition
} }
} }
// asks holds the ask id each call in flight carried (stdio.AskHeader), by its body's bytes, while its handler runs.
var asks sync.Map // unsafe.Pointer → string
// AskOf is the ask id the call whose body a SeatHandler was handed carried in stdio.AskHeader (design 47 H2 §775;
// H-A-351): what a holder in a process takes the ask once by. Empty when it carried none. Valid while the handler runs.
func AskOf(body json.RawMessage) string {
if len(body) == 0 {
return ""
}
if a, ok := asks.Load(unsafe.Pointer(unsafe.SliceData(body))); ok {
return a.(string)
}
return ""
}
// answerCall runs h for one call and replies {result, error, node}; a panic in h is the call's error, never silence. // answerCall runs h for one call and replies {result, error, node}; a panic in h is the call's error, never silence.
func (c *Conn) answerCall(msg *nats.Msg, pattern string, h heldHandler) { func (c *Conn) answerCall(msg *nats.Msg, pattern string, h heldHandler) {
caller := "" caller := ""
@@ -177,7 +195,13 @@ func (c *Conn) answerCall(msg *nats.Msg, pattern string, h heldHandler) {
reply.Error = fmt.Sprintf("%s failed: %v", msg.Subject, r) reply.Error = fmt.Sprintf("%s failed: %v", msg.Subject, r)
} }
}() }()
result, held, err := h(caller, json.RawMessage(msg.Data), wait) body := json.RawMessage(msg.Data)
if ask := msg.Header.Get(stdio.AskHeader); ask != "" && len(body) > 0 {
key := unsafe.Pointer(unsafe.SliceData(body))
asks.Store(key, ask)
defer asks.Delete(key)
}
result, held, err := h(caller, body, wait)
switch { switch {
case err != nil: case err != nil:
reply.Error = err.Error() reply.Error = err.Error()
+40 -3
View File
@@ -257,7 +257,7 @@ func (s State) put(key string, value any) (uint64, error) {
return rev, nil return rev, nil
} }
// Keys is every key with a current value, sorted; none is an empty list. // Keys is every key with a current value, sorted; none is an empty list. A keep (stdio.KeepPrefix) is not an entry and is left out.
// Keys waits out a bus that answers nothing for a few seconds (busretry): only a request that reached no one is asked again. // Keys waits out a bus that answers nothing for a few seconds (busretry): only a request that reached no one is asked again.
func (s State) Keys() ([]string, error) { func (s State) Keys() ([]string, error) {
return busretry.Do(s.what("keys"), func() ([]string, error) { return s.keys() }, nil) return busretry.Do(s.what("keys"), func() ([]string, error) { return s.keys() }, nil)
@@ -277,8 +277,14 @@ func (s State) keys() ([]string, error) {
if err != nil { if err != nil {
return nil, fmt.Errorf("%s's state %s, keys: %w", s.Module, s.Name, err) return nil, fmt.Errorf("%s's state %s, keys: %w", s.Module, s.Name, err)
} }
sort.Strings(keys) entries := keys[:0]
return keys, nil for _, k := range keys {
if !stdio.IsKeep(k) {
entries = append(entries, k)
}
}
sort.Strings(entries)
return entries, nil
} }
// watchPattern is a key narrowing as the bus names it: `*` stays one name, `**` is the rest, empty is every key. // watchPattern is a key narrowing as the bus names it: `*` stays one name, `**` is the rest, empty is every key.
@@ -334,6 +340,9 @@ func (s State) Watch(key string, handle func(stdio.StateChange) error) error {
} }
} }
deliver := func(e jetstream.KeyValueEntry, current bool) error { deliver := func(e jetstream.KeyValueEntry, current bool) error {
if stdio.IsKeep(e.Key()) {
return nil // a keep (stdio.KeepPrefix) is not an entry of the state: no watcher hears it
}
c := stdio.StateChange{State: s.Name, Key: e.Key(), Op: "put", Revision: e.Revision(), Current: current} c := stdio.StateChange{State: s.Name, Key: e.Key(), Op: "put", Revision: e.Revision(), Current: current}
if e.Operation() == jetstream.KeyValuePut { if e.Operation() == jetstream.KeyValuePut {
c.Value = json.RawMessage(e.Value()) c.Value = json.RawMessage(e.Value())
@@ -398,3 +407,31 @@ func (s State) delete(key string) error {
} }
return nil return nil
} }
// StateOver is a module's state read and written through kv, a key-value store bound over a link of the caller's own
// rather than a Conn (H-A-364): the node-engine, which serves its seat over its own link, takes asks once on its own
// taken state with it. module and name name it in errors.
func StateOver(module, name string, kv jetstream.KeyValue) *State {
return &State{Module: module, Name: name, kv: func(context.Context) (jetstream.KeyValue, error) { return kv, nil }}
}
// TakenState is the state a holder of a kept call keeps the ids of the asks it took in: stdio.TakenState.
const TakenState = stdio.TakenState
// TakenKey is the key an ask taken from seat is kept under in TakenState: stdio.TakenKey.
func TakenKey(seat, ask string) string { return stdio.TakenKey(seat, ask) }
// TakeOnce says whether this holder takes the ask ask of seat now (design 47 H2 §775; ADR 0668 §2), as
// stdio.KeptState.TakeOnce does for a bundle: the first time it is given, it is kept under TakenKey for the ask's bound
// and TakeOnce answers true; given again within the bound, false, and the holder acts once. s is the holder's
// TakenState, declared `key-ttl`. An ask with no id, or an id that is not one key, is refused: a kept call carries its id.
func (s State) TakeOnce(seat, ask string, bound time.Duration) (bool, error) {
if p := stdio.TakenProblem(seat, ask); p != "" {
return false, fmt.Errorf("taking an ask of %s: %s", seat, p)
}
_, err := s.CreateTTL(TakenKey(seat, ask), map[string]string{"seat": seat, "ask": ask}, max(bound, MinTTL))
if errors.Is(err, stdio.ErrChanged) {
return false, nil
}
return err == nil, err
}
+27
View File
@@ -4,7 +4,9 @@ package process
import ( import (
"errors" "errors"
"fmt"
"strings" "strings"
"sync"
"testing" "testing"
"time" "time"
@@ -199,6 +201,31 @@ func TestStatePutAndKeysOnAGrantedBucket(t *testing.T) {
if err != nil || strings.Join(keys, ",") != "a,b" { if err != nil || strings.Join(keys, ",") != "a,b" {
t.Fatalf("Keys: %v, %v, want a,b", keys, err) t.Fatalf("Keys: %v, %v, want a,b", keys, err)
} }
// Design 47 H2 §782: one connection's state calls are safe at once: gets, puts, keys and watches from many goroutines
// through the one handle, under the race detector.
var wg sync.WaitGroup
errs := make(chan error, 16*4)
for i := range 16 {
wg.Add(1)
go func() {
defer wg.Done()
key := fmt.Sprintf("c%d", i)
_, err := s.Put(key, i)
errs <- err
_, err = s.Get(key)
errs <- err
_, err = s.Keys()
errs <- err
errs <- s.Watch(key, func(stdio.StateChange) error { return nil })
}()
}
wg.Wait()
close(errs)
for err := range errs {
if err != nil {
t.Fatalf("a concurrent state call: %v", err)
}
}
} }
// 1840/S2: given a process connection granted its bucket, which already holds two keys and a deleted one, // 1840/S2: given a process connection granted its bucket, which already holds two keys and a deleted one,
+90 -18
View File
@@ -3,6 +3,7 @@ package process
import ( import (
"context" "context"
"errors" "errors"
"fmt"
"sort" "sort"
"strings" "strings"
"sync" "sync"
@@ -227,6 +228,79 @@ func TestStatePutWritesAKeyWhole(t *testing.T) {
if rev, err := dark.Put("k", 1); err != nil || rev == 0 || blackedOut != 0 { if rev, err := dark.Put("k", 1); err != nil || rev == 0 || blackedOut != 0 {
t.Fatalf("a Put through a short blackout: %d, %v", rev, err) t.Fatalf("a Put through a short blackout: %d, %v", rev, err)
} }
// Design 47 H2 §775: a holder given the same ask id twice acts once; the id is kept under <seat>.<ask> with the
// ask's bound as its time to live; an ask with no id, or one that is not one key, is refused.
tkv := newFakeKV()
taken := StateOver("mesh-host", TakenState, tkv) // H-A-364: over a store the caller bound itself
acts := 0
for range 2 {
if first, err := taken.TakeOnce("mesh-builds", "a-7", 10*time.Minute); err != nil {
t.Fatal(err)
} else if first {
acts++
}
}
if acts != 1 || !tkv.withTTL[TakenKey("mesh-builds", "a-7")] || TakenKey("mesh-builds", "a-7") != "mesh-builds.a-7" {
t.Fatalf("acted %d times, keys with a TTL %v", acts, tkv.withTTL)
}
if first, err := taken.TakeOnce("mesh-wants", "a-7", time.Minute); !first || err != nil {
t.Fatalf("the same id on another seat is another ask: %v, %v", first, err)
}
for _, bad := range [][2]string{{"mesh-builds", ""}, {"mesh-builds", "a.7"}, {"", "a-8"}} {
if _, err := taken.TakeOnce(bad[0], bad[1], time.Minute); err == nil {
t.Errorf("seat %q, ask %q was taken", bad[0], bad[1])
}
}
// Design 47 H2 §812 (H-A-380, H-A-386): a process's write that takes its state past prune-mark prunes it, oldest first
// by revision, to prune-target, in one journal line, reading the figures only at the bind and after the prune; a key
// kept under _keep/<key> survives, and no reader counts the keep.
t.Run("a write past its mark prunes to its target and a kept key survives", func(t *testing.T) {
var lines []string
sayPrune = func(line string) { lines = append(lines, line) }
t.Cleanup(func() { sayPrune = func(string) {} })
kv := &pruneKV{fakeKV: newFakeKV(), cap: 10_000}
s, err := stateOn(kv).Pruned(stdio.Prune{Mark: 70, Target: 50})
if err != nil {
t.Fatal(err)
}
value := strings.Repeat("x", 300)
if _, err := s.Put("k00", value); err != nil {
t.Fatal(err)
}
if err := s.Keep("k00", time.Now().Add(time.Hour)); err != nil {
t.Fatal(err)
}
if err := s.Keep("k01", time.Now().Add(-time.Hour)); err == nil {
t.Fatal("a keep until a time past was taken")
}
for i := 1; i < 18; i++ {
if _, err := s.Put(fmt.Sprintf("k%02d", i), value); err != nil {
t.Fatal(err)
}
if len(lines) == 0 && kv.held()*100 > 70*10_000 {
t.Fatalf("the state holds %d of 10000 bytes after k%02d and was not pruned", kv.held(), i)
}
}
if len(lines) != 1 || !strings.Contains(lines[0], "pruned the state mesh-mail's sends") {
t.Fatalf("the prunes said %q, want one line", lines)
}
if kv.statuss != 2 {
t.Fatalf("the figures were read %d times, want 2: at the bind and after the prune", kv.statuss)
}
if held := kv.held(); held*100 > 50*10_000 {
t.Fatalf("the prune left %d of 10000 bytes, above its target of 50 %%", held)
}
keys, err := s.Keys()
if err != nil {
t.Fatal(err)
}
if keys[0] != "k00" || strings.Contains(strings.Join(keys, " "), "_keep") || keys[1] == "k01" || keys[len(keys)-1] != "k17" {
t.Fatalf("after the prune the readers see %v: want k00 kept, the oldest others gone, k17 there, no keep", keys)
}
if e, _ := s.Get(stdio.KeepKey("k00")); e == nil {
t.Fatal("the keep itself was pruned")
}
})
} }
// 1840/S1: given a state, when its keys are listed, then they come sorted, and none is an empty list, not an error. // 1840/S1: given a state, when its keys are listed, then they come sorted, and none is an empty list, not an error.
@@ -298,25 +372,23 @@ func TestStateWatchHandsCurrentValuesThenChanges(t *testing.T) {
t.Fatalf("no change %+v", want) t.Fatalf("no change %+v", want)
} }
} }
} // 1840/S2: a key narrowing reaches the bus as a subject pattern: `*` one name, `**` the rest, empty every key.
t.Run("narrowing", func(t *testing.T) {
// 1840/S2: a key narrowing reaches the bus as a subject pattern: `*` one name, `**` the rest, empty every key. for key, want := range map[string]string{"": ">", "a.b": "a.b", "a.*": "a.*", "a.**": "a.>", "**": ">"} {
func TestStateWatchNarrowing(t *testing.T) { if got := watchPattern(key); got != want {
for key, want := range map[string]string{"": ">", "a.b": "a.b", "a.*": "a.*", "a.**": "a.>", "**": ">"} { t.Errorf("watchPattern(%q) = %q, want %q", key, got, want)
if got := watchPattern(key); got != want { }
t.Errorf("watchPattern(%q) = %q, want %q", key, got, want)
} }
} })
} // 1840/S2: given a handler that refuses a current value, then Watch returns its error.
t.Run("a handler's error on the current values is returned", func(t *testing.T) {
// 1840/S2: given a handler that refuses a current value, then Watch returns its error. kv := newFakeKV()
func TestStateWatchReturnsAHandlersErrorOnCurrentValues(t *testing.T) { kv.initial = []jetstream.KeyValueEntry{watchEntry{fakeEntry{key: "a", value: []byte(`1`), rev: 1}, jetstream.KeyValuePut}}
kv := newFakeKV() boom := errors.New("boom")
kv.initial = []jetstream.KeyValueEntry{watchEntry{fakeEntry{key: "a", value: []byte(`1`), rev: 1}, jetstream.KeyValuePut}} if err := stateOn(kv).Watch("", func(stdio.StateChange) error { return boom }); !errors.Is(err, boom) {
boom := errors.New("boom") t.Fatalf("Watch: %v, want the handler's error", err)
if err := stateOn(kv).Watch("", func(stdio.StateChange) error { return boom }); !errors.Is(err, boom) { }
t.Fatalf("Watch: %v, want the handler's error", err) })
}
} }
// 1840/S2: given a connection that closes before the current values arrive, then Watch returns an error. // 1840/S2: given a connection that closes before the current values arrive, then Watch returns an error.
+373
View File
@@ -0,0 +1,373 @@
package stdio
import (
"encoding/json"
"errors"
"fmt"
"sort"
"strconv"
"strings"
"sync"
"time"
"git.novox.be/novox/mesh-sdk/go/buscalls"
)
// A kept store's owner prunes it toward its cap, judged at its own writes (design 47 H2 §812; H-A-380, H-A-386): when
// the fill passes prune-mark of the cap, the oldest keys by their current revision are removed until it is down to
// prune-target, one journal line per prune, with no extra read, no poll and no timer. A key kept by a person
// (`<module>_state_keep`) is never pruned before its until: the keep lives in the pruned state itself under KeepPrefix.
// The prune's settings and their defaults: prune-mark below the bus module's raise mark of 75 %.
const (
PruneMarkSetting = "prune-mark"
PruneTargetSetting = "prune-target"
PruneMarkDefault = 70
PruneTargetDefault = 50
pruneSettingPercent = "a percentage of the cap between 1 and 100"
)
// KeepPrefix is the reserved prefix a keep lives under in the state it keeps a key of (H-A-386): `_keep/<key>`, with
// its until. A keep is never pruned and never counted as an entry by the readers (Keys, Page, Watch).
const KeepPrefix = "_keep/"
// KeepKey is the key the keep of key lives under.
func KeepKey(key string) string { return KeepPrefix + key }
// IsKeep is whether key is a keep rather than an entry of its state.
func IsKeep(key string) bool { return strings.HasPrefix(key, KeepPrefix) }
// Keep is a keep's value: the key it keeps is never pruned before Until.
type Keep struct {
Until time.Time `json:"until"`
}
// SettingPercent is the config value key read as a percentage ("70" or "70%"): def when none is composed or it is
// empty, an error naming the key for a value that is no whole number from 1 to 100.
func SettingPercent(key string, def int) (int, error) {
v, ok := Setting(key)
if v = strings.TrimSpace(v); !ok || v == "" {
return def, nil
}
n, err := strconv.Atoi(strings.TrimSpace(strings.TrimSuffix(v, "%")))
if err != nil || n < 1 || n > 100 {
return 0, fmt.Errorf("the setting %s (%s) holds %q, which is not %s", key, SettingWord(key), v, pruneSettingPercent)
}
return n, nil
}
// Prune is where a prune starts and where it ends, in percent of the cap.
type Prune struct {
Mark, Target int
}
// PruneSettings is the module's prune-mark and prune-target, read through the settings reader with their defaults; a
// target not below the mark is refused, naming both.
func PruneSettings() (Prune, error) {
mark, err := SettingPercent(PruneMarkSetting, PruneMarkDefault)
if err != nil {
return Prune{}, err
}
target, err := SettingPercent(PruneTargetSetting, PruneTargetDefault)
if err != nil {
return Prune{}, err
}
if target >= mark {
return Prune{}, fmt.Errorf("the setting %s (%d %%) is not below %s (%d %%): a prune would never end below its mark",
PruneTargetSetting, target, PruneMarkSetting, mark)
}
return Prune{Mark: mark, Target: target}, nil
}
// Passed is whether bytes of a cap of maxBytes passes the mark; an entry with no cap never does.
func (p Prune) Passed(bytes, maxBytes uint64) bool {
return maxBytes > 0 && bytes*100 > uint64(p.Mark)*maxBytes
}
// PruneEntry is one current value of a pruned state as the prune reads it: its key, its current revision and the
// bytes it holds on the bus.
type PruneEntry struct {
Key string
Revision uint64
Bytes uint64
Value []byte
}
// Choose is the keys a prune removes, oldest first by their current revision, until bytes is down to the target of
// maxBytes, and how many it skipped for a keep whose until is still to come. A keep itself is never chosen; a keep that
// cannot be read keeps its key (a prune never removes what a person may have kept).
func (p Prune) Choose(entries []PruneEntry, now time.Time, bytes, maxBytes uint64) (drop []string, kept int) {
keeps := map[string]bool{}
for _, e := range entries {
if !IsKeep(e.Key) {
continue
}
var k Keep
if err := json.Unmarshal(e.Value, &k); err != nil || k.Until.After(now) {
keeps[strings.TrimPrefix(e.Key, KeepPrefix)] = true
}
}
sorted := append([]PruneEntry(nil), entries...)
sort.Slice(sorted, func(i, j int) bool { return sorted[i].Revision < sorted[j].Revision })
target := uint64(p.Target) * maxBytes / 100
for _, e := range sorted {
if bytes <= target {
break
}
if IsKeep(e.Key) {
continue
}
if keeps[e.Key] {
kept++
continue
}
drop = append(drop, e.Key)
bytes -= min(bytes, e.Bytes)
}
return drop, kept
}
// Pruned is what one prune did: the state, how many keys it removed and skipped for a keep, and its fill before and
// after against the cap.
type Pruned struct {
State string `json:"state"`
Removed int `json:"removed"`
Kept int `json:"kept"`
From uint64 `json:"from-bytes"`
To uint64 `json:"to-bytes"`
MaxBytes uint64 `json:"max-bytes"`
Mark int `json:"mark"`
Target int `json:"target"`
}
// Line is the prune's one journal line.
func (r Pruned) Line() string {
return fmt.Sprintf("pruned the state %s: removed %d keys oldest first (%d kept by a keep), from %d to %d bytes of its cap of %d (mark %d %%, target %d %%)",
r.State, r.Removed, r.Kept, r.From, r.To, r.MaxBytes, r.Mark, r.Target)
}
// Prunable is a state its owner prunes: the generic tools `<module>_state_prune_now` and `<module>_state_keep` act on it.
type Prunable interface {
// PruneNow prunes the state to its target now, whatever its fill.
PruneNow() (Pruned, error)
// Keep keeps key from the prune until the time given.
Keep(key string, until time.Time) error
}
// Pruner is the prune helper of one state, the same for a process and a bundle: Entries reads the state's current
// values (keeps included) once per prune, Remove removes one key, Figures reads the entry's bytes and cap. A process
// gives Wrote the bytes each write puts and Figures is read at Bind and after each prune; a bundle gives Filled the
// fill its write's answer carries.
type Pruner struct {
State string
Prune Prune
Entries func() ([]PruneEntry, error)
Remove func(key string) error
Figures func() (bytes, maxBytes uint64, err error)
// Say writes the prune's journal line.
Say func(line string)
Now func() time.Time
mu sync.Mutex
bytes, limit uint64
}
// Bind reads the entry's figures once, the base of the running sum Wrote keeps.
func (p *Pruner) Bind() error {
bytes, limit, err := p.Figures()
if err != nil {
return fmt.Errorf("the state %s's fill could not be read for its prune: %w", p.State, err)
}
p.mu.Lock()
p.bytes, p.limit = bytes, limit
p.mu.Unlock()
return nil
}
// Wrote adds the bytes a write put to the running sum and prunes when it passes the mark: the answer is the prune it
// ran, or nil.
func (p *Pruner) Wrote(n uint64) (*Pruned, error) {
p.mu.Lock()
defer p.mu.Unlock()
p.bytes += n
if !p.Prune.Passed(p.bytes, p.limit) {
return nil, nil
}
r, err := p.pruneLocked(p.bytes, p.limit, true)
return &r, err
}
// Filled judges the fill a write's answer carries and prunes when it passes the mark: the answer is the prune it ran,
// or nil.
func (p *Pruner) Filled(f buscalls.Fill) (*Pruned, error) {
p.mu.Lock()
defer p.mu.Unlock()
p.bytes, p.limit = f.Bytes, f.MaxBytes
if !p.Prune.Passed(f.Bytes, f.MaxBytes) {
return nil, nil
}
r, err := p.pruneLocked(f.Bytes, f.MaxBytes, false)
return &r, err
}
// PruneNow reads the figures and prunes to the target now.
func (p *Pruner) PruneNow() (Pruned, error) {
bytes, limit, err := p.Figures()
if err != nil {
return Pruned{State: p.State}, fmt.Errorf("the state %s's fill could not be read for its prune: %w", p.State, err)
}
p.mu.Lock()
defer p.mu.Unlock()
if limit == 0 {
return Pruned{State: p.State}, fmt.Errorf("the state %s names no cap, so it has no target to prune to", p.State)
}
return p.pruneLocked(bytes, limit, true)
}
// pruneLocked removes the oldest keys from bytes down to the target of limit; reread reads the figures after it, the
// new base of the running sum.
func (p *Pruner) pruneLocked(bytes, limit uint64, reread bool) (Pruned, error) {
r := Pruned{State: p.State, From: bytes, MaxBytes: limit, Mark: p.Prune.Mark, Target: p.Prune.Target}
entries, err := p.Entries()
if err != nil {
return r, fmt.Errorf("the state %s could not be read for its prune: %w", p.State, err)
}
// The running sum is an upper bound (an overwrite's past value is the bucket's history to bound), so what the
// current values hold is the start when it is lower.
var held uint64
for _, e := range entries {
held += e.Bytes
}
start := min(bytes, held)
now := time.Now
if p.Now != nil {
now = p.Now
}
drop, kept := p.Prune.Choose(entries, now(), start, limit)
r.Kept, r.To = kept, start
sizes := map[string]uint64{}
for _, e := range entries {
sizes[e.Key] = e.Bytes
}
var errs []error
for _, key := range drop {
if err := p.Remove(key); err != nil {
errs = append(errs, fmt.Errorf("%s: %w", key, err))
continue
}
r.Removed++
r.To -= min(r.To, sizes[key])
}
if reread {
if b, l, err := p.Figures(); err == nil {
r.To, r.MaxBytes = b, l
} else {
errs = append(errs, fmt.Errorf("the fill after the prune: %w", err))
}
}
p.bytes, p.limit = r.To, r.MaxBytes
if p.Say != nil {
p.Say(r.Line())
}
if len(errs) > 0 {
return r, fmt.Errorf("the prune of the state %s: %w", p.State, errors.Join(errs...))
}
return r, nil
}
// PutOverhead is what a write puts on the bus beside its key and its value, an upper bound: the bucket's subject
// prefix, the message's headers and its record.
const PutOverhead = 96
// PutBytes is what a write of value under key puts on the bus, as the prune helper counts it.
func PutBytes(key string, value []byte) uint64 { return uint64(len(key) + len(value) + PutOverhead) }
// PrunedState is a state a bundle prunes at its writes (§812): Put judges the fill the runtime's put answer carries
// (DMC-14, H-A-386) and prunes when it passes the mark. Its other calls are the state's own.
type PrunedState struct {
KeptState
pruner *Pruner
unsaid sync.Once
}
// Pruned is the state pruned by p at its writes.
func (s KeptState) Pruned(p Prune) *PrunedState {
ps := &PrunedState{KeptState: s}
ps.pruner = &Pruner{State: s.name, Prune: p, Say: func(line string) { sayf("%s", line) },
Remove: s.Delete,
Figures: func() (uint64, uint64, error) {
i, err := s.Info()
if err != nil {
return 0, 0, err
}
return i.Bytes, uint64(max(i.MaxBytes, 0)), nil
},
Entries: func() ([]PruneEntry, error) {
var out []PruneEntry
cursor := ""
for {
page, err := s.page(cursor, 768<<10, stateTimeout/2)
if err != nil {
return nil, err
}
for _, e := range page.Entries {
out = append(out, PruneEntry{Key: e.Key, Revision: e.Revision, Bytes: PutBytes(e.Key, e.Value), Value: e.Value})
}
if page.Next == "" || page.Next == cursor {
return out, nil
}
cursor = page.Next
}
}}
return ps
}
// Put writes a key whole and returns the revision written; the fill its answer carries is judged, and past the mark
// the state is pruned to its target before Put returns. A runtime whose answer carries no fill is said once, as a
// state that is never pruned.
func (s *PrunedState) Put(key string, value any) (uint64, error) {
raw, err := s.ask("put", map[string]any{"key": key, "value": value})
if err != nil {
return 0, err
}
var put struct {
Revision uint64 `json:"revision"`
Fill *buscalls.Fill `json:"fill"`
}
if err := json.Unmarshal(raw, &put); err != nil {
return 0, err
}
if put.Fill == nil {
s.unsaid.Do(func() {
sayf("the state %s is never pruned: the runtime's put answer carries no fill (design 47 H2 §812)", s.name)
})
return put.Revision, nil
}
if _, err := s.pruner.Filled(*put.Fill); err != nil {
return put.Revision, err
}
return put.Revision, nil
}
// PruneNow prunes the state to its target now.
func (s *PrunedState) PruneNow() (Pruned, error) { return s.pruner.PruneNow() }
// Keep keeps key from the prune until until, written under KeepKey.
func (s *PrunedState) Keep(key string, until time.Time) error {
if err := KeepProblem(key, until); err != nil {
return err
}
_, err := s.Put(KeepKey(key), Keep{Until: until.UTC()})
return err
}
// KeepProblem is why key cannot be kept until until, or nil: a process and a bundle check a keep alike.
func KeepProblem(key string, until time.Time) error {
switch {
case key == "" || IsKeep(key):
return fmt.Errorf("%q is not a key a keep keeps", key)
case !until.After(time.Now()):
return fmt.Errorf("a keep until %s keeps nothing: until is a time still to come", until.Format(time.RFC3339))
}
return nil
}
+61
View File
@@ -0,0 +1,61 @@
package seal
import (
"bytes"
"crypto/sha256"
"encoding/base64"
"encoding/json"
"testing"
"golang.org/x/crypto/nacl/box"
)
// anonymousFixture holds the NaCl anonymous boxes golang.org/x/crypto/nacl/box seals (the box the vault's intake opens),
// with their one-time keys, for the SDK's TypeScript sealAnonymous to make byte for byte (design 47 H2, H-A-407).
type anonymousFixture struct {
About string `json:"about"`
Recipient struct {
Public string `json:"public"`
Private string `json:"private"`
} `json:"recipient"`
Vectors []struct {
Plaintext string `json:"plaintext"`
EphSecret string `json:"ephSecret"`
Sealed string `json:"sealed"`
} `json:"vectors"`
}
const anonymousFixturePath = "testdata/sealed-anonymous-by-go.json"
// anonymousVectors seals each plaintext with box.SealAnonymous to a recipient and one-time keys derived from fixed
// labels: test keys that guard nothing.
func anonymousVectors(t *testing.T) anonymousFixture {
t.Helper()
b64 := base64.StdEncoding.EncodeToString
seed := sha256.Sum256([]byte("mesh-sdk anonymous box test recipient"))
pub, priv, err := box.GenerateKey(bytes.NewReader(seed[:]))
if err != nil {
t.Fatal(err)
}
var f anonymousFixture
f.About = "Made by this package's anonymous_test.go with golang.org/x/crypto/nacl/box's SealAnonymous, its one-time keys fixed; the test proves the file is Go's bytes on every run. Test keys; they guard nothing."
f.Recipient.Public, f.Recipient.Private = b64(pub[:]), b64(priv[:])
for i, plain := range []string{"", "a token minted for the forge", "ünïcode and a longer value: " + string(bytes.Repeat([]byte("x"), 300))} {
eph := sha256.Sum256([]byte{byte(i), 'e', 'p', 'h'})
sealed, err := box.SealAnonymous(nil, []byte(plain), pub, bytes.NewReader(eph[:]))
if err != nil {
t.Fatal(err)
}
f.Vectors = append(f.Vectors, struct {
Plaintext string `json:"plaintext"`
EphSecret string `json:"ephSecret"`
Sealed string `json:"sealed"`
}{plain, b64(eph[:]), b64(sealed)})
}
return f
}
func mustJSON(v any) string {
raw, _ := json.Marshal(v)
return string(raw)
}
+68 -35
View File
@@ -6,6 +6,8 @@ import (
"encoding/json" "encoding/json"
"os" "os"
"testing" "testing"
"golang.org/x/crypto/nacl/box"
) )
type fixture struct { type fixture struct {
@@ -75,6 +77,39 @@ func TestSealIsByteForByteTheLicenceManagersBox(t *testing.T) {
t.Fatalf("reopened %q, %v", plain, err) t.Fatalf("reopened %q, %v", plain, err)
} }
} }
// The anonymous-box fixture the TypeScript tests read is what box.SealAnonymous makes, and each opens with the
// recipient's key as the vault's intake opens it (box.OpenAnonymous). MESH_SDK_WRITE_FIXTURES=1 writes it anew.
t.Run("the anonymous box fixture is Go's bytes", func(t *testing.T) {
want := anonymousVectors(t)
if os.Getenv("MESH_SDK_WRITE_FIXTURES") == "1" {
raw, _ := json.MarshalIndent(want, "", " ")
if err := os.WriteFile(anonymousFixturePath, append(raw, '\n'), 0o644); err != nil {
t.Fatal(err)
}
}
raw, err := os.ReadFile(anonymousFixturePath)
if err != nil {
t.Fatal(err)
}
var got anonymousFixture
if err := json.Unmarshal(raw, &got); err != nil {
t.Fatal(err)
}
if g, w := mustJSON(got), mustJSON(want); g != w {
t.Fatalf("the fixture is not Go's bytes:\n%s\nwant\n%s", g, w)
}
var pub, priv [32]byte
p, _ := base64.StdEncoding.DecodeString(got.Recipient.Public)
k, _ := base64.StdEncoding.DecodeString(got.Recipient.Private)
copy(pub[:], p)
copy(priv[:], k)
for _, v := range got.Vectors {
sealed, _ := base64.StdEncoding.DecodeString(v.Sealed)
if out, ok := box.OpenAnonymous(nil, sealed, &pub, &priv); !ok || string(out) != v.Plaintext {
t.Errorf("a box does not open to %q: %q, %v", v.Plaintext, out, ok)
}
}
})
} }
// A box the agent module's TypeScript sealed (the fixture the licence manager keeps) opens here too. // A box the agent module's TypeScript sealed (the fixture the licence manager keeps) opens here too.
@@ -117,40 +152,38 @@ func TestABoxOpensOnlyForItsRecipient(t *testing.T) {
if again.Eph == box.Eph || again.IV == box.IV { if again.Eph == box.Eph || again.IV == box.IV {
t.Fatal("two boxes share a one-time key or iv") t.Fatal("two boxes share a one-time key or iv")
} }
} // A box changed in any field, or of another version, does not open.
t.Run("a tampered box does not open", func(t *testing.T) {
// A box changed in any field, or of another version, does not open. f := readFixture(t)
func TestATamperedBoxDoesNotOpen(t *testing.T) { good := f.Sealed[1].Box
f := readFixture(t) flip := func(s string) string {
good := f.Sealed[1].Box b, _ := base64.StdEncoding.DecodeString(s)
flip := func(s string) string { b[len(b)-1] ^= 1
b, _ := base64.StdEncoding.DecodeString(s) return base64.StdEncoding.EncodeToString(b)
b[len(b)-1] ^= 1
return base64.StdEncoding.EncodeToString(b)
}
for name, box := range map[string]Box{
"ct": {V: 1, Eph: good.Eph, IV: good.IV, Tag: good.Tag, Ct: flip(good.Ct)},
"tag": {V: 1, Eph: good.Eph, IV: good.IV, Tag: flip(good.Tag), Ct: good.Ct},
"iv": {V: 1, Eph: good.Eph, IV: flip(good.IV), Tag: good.Tag, Ct: good.Ct},
"eph": {V: 1, Eph: flip(good.Eph), IV: good.IV, Tag: good.Tag, Ct: good.Ct},
"version": {V: 2, Eph: good.Eph, IV: good.IV, Tag: good.Tag, Ct: good.Ct},
} {
if _, err := Open(box, f.Recipient.PrivateKey); err == nil {
t.Fatalf("a box with a changed %s opened", name)
} }
} for name, box := range map[string]Box{
} "ct": {V: 1, Eph: good.Eph, IV: good.IV, Tag: good.Tag, Ct: flip(good.Ct)},
"tag": {V: 1, Eph: good.Eph, IV: good.IV, Tag: flip(good.Tag), Ct: good.Ct},
// A key that is not X25519 PEM is refused, not misread. "iv": {V: 1, Eph: good.Eph, IV: flip(good.IV), Tag: good.Tag, Ct: good.Ct},
func TestAKeyOfAnotherKindIsRefused(t *testing.T) { "eph": {V: 1, Eph: flip(good.Eph), IV: good.IV, Tag: good.Tag, Ct: good.Ct},
if _, err := Seal("x", "not a key"); err == nil { "version": {V: 2, Eph: good.Eph, IV: good.IV, Tag: good.Tag, Ct: good.Ct},
t.Fatal("sealed to text") } {
} if _, err := Open(box, f.Recipient.PrivateKey); err == nil {
f := readFixture(t) t.Fatalf("a box with a changed %s opened", name)
if _, err := Open(f.Sealed[0].Box, f.Recipient.PublicKey); err == nil { }
t.Fatal("opened with a public key") }
} })
if _, err := Seal("x", f.Recipient.PrivateKey); err == nil { // A key that is not X25519 PEM is refused, not misread.
t.Fatal("sealed to a private key") t.Run("a key of another kind is refused", func(t *testing.T) {
} if _, err := Seal("x", "not a key"); err == nil {
t.Fatal("sealed to text")
}
f := readFixture(t)
if _, err := Open(f.Sealed[0].Box, f.Recipient.PublicKey); err == nil {
t.Fatal("opened with a public key")
}
if _, err := Seal("x", f.Recipient.PrivateKey); err == nil {
t.Fatal("sealed to a private key")
}
})
} }
+24
View File
@@ -0,0 +1,24 @@
{
"about": "Made by this package's anonymous_test.go with golang.org/x/crypto/nacl/box's SealAnonymous, its one-time keys fixed; the test proves the file is Go's bytes on every run. Test keys; they guard nothing.",
"recipient": {
"public": "n2nWtTM35RrjXe1pPBzIHWRfSvoE5AMFxFWA92lYmj4=",
"private": "0zveHnrRJV0at3GITmix/NpjX1sJPgsu0tGZIXFVKos="
},
"vectors": [
{
"plaintext": "",
"ephSecret": "CU2adSGwGEEx6/xxSvrQ8Vfq6Yc+kR+2yX7fFriYCbg=",
"sealed": "8qO+LLqjzgOtuE2KVM6bKDB3dMiMiAuEc0hgRwGe03wNBJ60VwAAIw4xPJLmmT1g"
},
{
"plaintext": "a token minted for the forge",
"ephSecret": "CvmgsKRsGyTmAFRD4EB0mAPpBVN3I4yLJJkkcfbqX0A=",
"sealed": "erK5lMtu+k90Thig1rpUq2jJ9DzF/WZWvVvMPNO+hiPF5uL5jnqNB7h3hQro13ZiKwK4O/hm3MvZm9glM8KqSBoeApTrVWnvP/Ekzg=="
},
{
"plaintext": "ünïcode and a longer value: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"ephSecret": "ypSqdS+hEEoCsEDT6K87sc/I/h9yi06j08c1bKEJAQw=",
"sealed": "QQ7wBpBtvQH4BvkicANk50VlTJ/puVD+BhRgD9ccAl6NriByxkFqxb3GQUy++HAhByqR9vd+NSSt59dVmjKIFdiiJKCvH6zgGWkHEcVBtn1F5PUzscO+yhEwxuuPK1pLJ24PBdcef9x111Yu4aKgG31mt5z0Bnxs9YZAobz8Nx2vkPYfz1Fzu6Tqqq9bElH9rbR/Ua+ChpGu0BgnKgAWRQlnXBOjrVUC4DFa4wFDfCROgFWC1rM3fQCd8Tm4OHpa6RMRhE9pafi8OMP0XIwUrL29JDkcyMtGPuDab3f6NTgGI+yTCHxNgbOupxeA18Ied7om9rt1oAsEfo2SrYEvzplFCgYpDuXmf693zNPFKuGHd18FZmQKwp6gODpO2t+UCEzJa5EB/9vaf44BWcRIDLWiLzx2Pg0QA3DxZziSL4eff9TOeN8qUHH5pYdU5Cdu7clbhImNoe9kqNSZb3NOwav+HZh4SjtfzcHrBTMWbKs8i0jZYLgxcEcr"
}
]
}
+70
View File
@@ -2,6 +2,8 @@ package stdio
import ( import (
"encoding/json" "encoding/json"
"errors"
"fmt"
"strings" "strings"
"time" "time"
) )
@@ -201,6 +203,38 @@ func (s KeptState) CreateTTL(key string, value any, ttl time.Duration) (uint64,
return s.revisionOf(s.ask("create", map[string]any{"key": key, "value": value, "ttl_seconds": ttlSeconds(ttl)})) return s.revisionOf(s.ask("create", map[string]any{"key": key, "value": value, "ttl_seconds": ttlSeconds(ttl)}))
} }
// TakenState is the state a holder of a kept call keeps the ids of the asks it took in (design 47 H2 §775, §820): a
// state of 8 MiB whose keys live the ask's bound and are deleted by their time to live alone, never pruned.
const TakenState = "taken"
// TakenKey is the key an ask taken from seat is kept under in TakenState: `<seat>.<ask>`.
func TakenKey(seat, ask string) string { return seat + "." + ask }
// TakenProblem is why seat and ask name no taken key, or empty: a seat's name and an ask's id are each one key token.
func TakenProblem(seat, ask string) string {
switch {
case ask == "" || strings.ContainsAny(ask, ".*> "):
return fmt.Sprintf("%q is not an ask id: an ask id holds no dot and no wildcard, naming one key and no other", ask)
case seat == "" || strings.ContainsAny(seat, ".*> "):
return fmt.Sprintf("%q is not a seat's name", seat)
}
return ""
}
// TakeOnce says whether this holder takes the ask ask of seat now (design 47 H2 §775; ADR 0668 §2; H-A-359): the
// first time it is given it is kept under TakenKey for the ask's bound and TakeOnce answers true; given again within
// the bound, false, and the holder acts once. s is the holder's TakenState, declared `key-ttl`.
func (s KeptState) TakeOnce(seat, ask string, bound time.Duration) (bool, error) {
if p := TakenProblem(seat, ask); p != "" {
return false, fmt.Errorf("taking an ask of %s: %s", seat, p)
}
_, err := s.CreateTTL(TakenKey(seat, ask), map[string]string{"seat": seat, "ask": ask}, max(bound, time.Second))
if errors.Is(err, ErrChanged) {
return false, nil
}
return err == nil, err
}
// Update writes a key only when it is still at revision, and returns the new one; a key changed // Update writes a key only when it is still at revision, and returns the new one; a key changed
// meanwhile is refused, so of two writers that read one value only the first writes. // meanwhile is refused, so of two writers that read one value only the first writes.
func (s KeptState) Update(key string, value any, revision uint64) (uint64, error) { func (s KeptState) Update(key string, value any, revision uint64) (uint64, error) {
@@ -230,3 +264,39 @@ func subjectMatches(pattern, subject string) bool {
} }
return len(p) == len(s) return len(p) == len(s)
} }
// WaitingAsk is one ask waiting in a seat's work queue, as the runtime reads it without taking it (design 47 H2 §777,
// H-A-410): the ask's id, the module that asked it and its age in seconds. Again says it was handed out and handed back
// (a nak) and no worker holds it: waiting again (H-A-410's addendum).
type WaitingAsk struct {
ID string `json:"id"`
Module string `json:"module"`
AgeSeconds float64 `json:"age_seconds"`
Again bool `json:"again,omitempty"`
}
// Waiting is the asks waiting in a seat's work queue, oldest first as the queue holds them; Capped says the runtime cut
// them at 768 KB.
type Waiting struct {
Asks []WaitingAsk `json:"asks"`
Capped bool `json:"capped"`
}
// QueueWaiting is the asks waiting in the work queue of seat, this holder's own queue, which a holder's asks tool answers
// (design 47 H2 §777, H-A-410): asked of the runtime as mesh/queue.waiting, which reads the queue's waiting messages
// without taking them. A refusal is the runtime's error.
func QueueWaiting(seat string) (Waiting, error) {
c, err := live()
if err != nil {
return Waiting{}, err
}
raw, err := c.ask("mesh/queue.waiting", map[string]any{"seat": seat}, seatTimeout)
if err != nil {
return Waiting{}, err
}
var w Waiting
if err := json.Unmarshal(raw, &w); err != nil {
return Waiting{}, fmt.Errorf("the runtime answered the waiting asks of %s in no form this reads: %w", seat, err)
}
return w, nil
}
+60 -5
View File
@@ -49,10 +49,13 @@ var Domains = []string{"Module", "Config", "Core", "Provisioning", "Identity and
// Definition is one seat's contract. // Definition is one seat's contract.
type Definition struct { type Definition struct {
Format int `json:"format"` Format int `json:"format"`
Seat string `json:"seat"` // Form is the definition's form (design 47 H2 §780; H-A-352): raised at every field its values, events, accepts and
Scope string `json:"scope"` // answers add or remove. Absent reads 1; below 1 is refused.
Grain string `json:"grain"` Form int `json:"form,omitempty"`
Seat string `json:"seat"`
Scope string `json:"scope"`
Grain string `json:"grain"`
// Decision is the record that made it a seat. // Decision is the record that made it a seat.
Decision string `json:"decision"` Decision string `json:"decision"`
// Domain is the glossary domain the seat belongs to, by its heading (ADR 0636 §5): the indexer takes a seat of the // Domain is the glossary domain the seat belongs to, by its heading (ADR 0636 §5): the indexer takes a seat of the
@@ -265,6 +268,40 @@ type Message struct {
// `accept.<stream>`, the kind in the body alone (design 47 G §600, A-170). Its generated names and an invoke name it // `accept.<stream>`, the kind in the body alone (design 47 G §600, A-170). Its generated names and an invoke name it
// `<stream>.<kind>`, so the same kind name may ride more than one stream (design 47 G §415). // `<stream>.<kind>`, so the same kind name may ride more than one stream (design 47 G §415).
Stream string `json:"stream,omitempty"` Stream string `json:"stream,omitempty"`
// The work queue's settings an accepted kind names (design 47 H2 §777; H-A-350 DMC-1, H-A-362), from which mesh-sdk's
// buscompose derives the seat's work-queue stream and its one shared worker: durations as Go writes them ("24h",
// "2m", "60s", "20s"), counts as integers. Each absent is buscompose's default.
MaxAge string `json:"max-age,omitempty"`
DuplicatesWindow string `json:"duplicates-window,omitempty"`
AckWait string `json:"ack-wait,omitempty"`
InProgress string `json:"in-progress,omitempty"`
MaxMsgs int `json:"max-msgs,omitempty"`
MaxAckPending int `json:"max-ack-pending,omitempty"`
MaxDeliveries int `json:"max-deliveries,omitempty"`
}
// QueueProblems is what is wrong with an accepted kind's work-queue settings: a duration that is not one above zero, or
// a count below zero.
func (m Message) QueueProblems(where string) Problems {
var ps Problems
for _, d := range []struct{ name, value string }{{"max-age", m.MaxAge}, {"duplicates-window", m.DuplicatesWindow},
{"ack-wait", m.AckWait}, {"in-progress", m.InProgress}} {
if d.value == "" {
continue
}
if v, err := time.ParseDuration(d.value); err != nil || v <= 0 {
ps = append(ps, Problem{where + "." + d.name, fmt.Sprintf("%q is not a duration above zero, as \"24h\" or \"60s\"", d.value)})
}
}
for _, n := range []struct {
name string
value int
}{{"max-msgs", m.MaxMsgs}, {"max-ack-pending", m.MaxAckPending}, {"max-deliveries", m.MaxDeliveries}} {
if n.value < 0 {
ps = append(ps, Problem{where + "." + n.name, fmt.Sprintf("%d is below zero", n.value)})
}
}
return ps
} }
// What an event's keep says where it says less (design 47 G §396, §331). // What an event's keep says where it says less (design 47 G §396, §331).
@@ -468,7 +505,9 @@ type Path struct {
// Part is verbs, events and types several definitions include whole. // Part is verbs, events and types several definitions include whole.
type Part struct { type Part struct {
Format int `json:"format"` Format int `json:"format"`
// Form is the part's own form, for what it adds (H-A-352): absent reads 1; below 1 is refused.
Form int `json:"form,omitempty"`
Part string `json:"part"` Part string `json:"part"`
Description string `json:"description,omitempty"` Description string `json:"description,omitempty"`
Verbs []Verb `json:"verbs,omitempty"` Verbs []Verb `json:"verbs,omitempty"`
@@ -528,9 +567,21 @@ func Parse(raw []byte) (Definition, error) {
if ps := d.check(); len(ps) > 0 { if ps := d.check(); len(ps) > 0 {
return Definition{}, ps return Definition{}, ps
} }
d.Form = formRead(d.Form)
return d, nil return d, nil
} }
// formRead is a form as read: absent is 1 (H-A-352).
func formRead(n int) int { return max(n, 1) }
// formProblems refuses a form below 1; absent reads 1.
func formProblems(n int) Problems {
if n < 0 {
return Problems{{"form", fmt.Sprintf("form %d: a form is 1 or more, and absent reads 1", n)}}
}
return nil
}
// ParsePart reads one part. // ParsePart reads one part.
func ParsePart(raw []byte) (Part, error) { func ParsePart(raw []byte) (Part, error) {
var p Part var p Part
@@ -544,11 +595,13 @@ func ParsePart(raw []byte) (Part, error) {
if !wordName.MatchString(p.Part) { if !wordName.MatchString(p.Part) {
ps = append(ps, Problem{"part", "missing, or not a lower-case name"}) ps = append(ps, Problem{"part", "missing, or not a lower-case name"})
} }
ps = append(ps, formProblems(p.Form)...)
ps = append(ps, checkVerbs(p.Verbs, true)...) ps = append(ps, checkVerbs(p.Verbs, true)...)
ps = append(ps, checkMessages("events", p.Events, true)...) ps = append(ps, checkMessages("events", p.Events, true)...)
if len(ps) > 0 { if len(ps) > 0 {
return Part{}, ps return Part{}, ps
} }
p.Form = formRead(p.Form)
return p, nil return p, nil
} }
@@ -633,6 +686,7 @@ func (d Definition) check() Problems {
if d.Format != Format { if d.Format != Format {
ps = append(ps, Problem{"format", formatProblem(d.Format)}) ps = append(ps, Problem{"format", formatProblem(d.Format)})
} }
ps = append(ps, formProblems(d.Form)...)
if d.Seat == "" { if d.Seat == "" {
ps = append(ps, Problem{"seat", "missing"}) ps = append(ps, Problem{"seat", "missing"})
} else if !seatName.MatchString(d.Seat) { } else if !seatName.MatchString(d.Seat) {
@@ -868,6 +922,7 @@ func checkMessages(field string, ms []Message, whole bool) Problems {
ps = append(ps, Problem{where + ".keep", "an event of one subject kept last per subject is one message: give it a subject with parts"}) ps = append(ps, Problem{where + ".keep", "an event of one subject kept last per subject is one message: give it a subject with parts"})
} }
} }
ps = append(ps, m.QueueProblems(where)...)
if m.Subject != "" && field != "events" { if m.Subject != "" && field != "events" {
ps = append(ps, Problem{where + ".subject", "only an event carries a subject of its own"}) ps = append(ps, Problem{where + ".subject", "only an event carries a subject of its own"})
} else if why := checkSubject(m); why != "" { } else if why := checkSubject(m); why != "" {
+33
View File
@@ -154,6 +154,10 @@ func TestADefinitionIsReadStrictlyNamingWhatIsWrong(t *testing.T) {
`"accepts":[{"name":"step","body":{},"stream":"check"},{"name":"step","body":{},"stream":"check"}],"events":`, 1), `"step" twice`}, `"accepts":[{"name":"step","body":{},"stream":"check"},{"name":"step","body":{},"stream":"check"}],"events":`, 1), `"step" twice`},
{"a stream that is none", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"stream":"mail"}],"events":`, 1), {"a stream that is none", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"stream":"mail"}],"events":`, 1),
`accepts[0].stream: "mail" is not check or delivery`}, `accepts[0].stream: "mail" is not check or delivery`},
// Design 47 H2 §777, H-A-362: an accepted kind names its work queue's settings, durations as Go writes them.
{"a work queue's settings", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"max-age":"24h","duplicates-window":"2m","ack-wait":"60s","in-progress":"20s","max-msgs":10000,"max-ack-pending":64,"max-deliveries":5}],"events":`, 1), ""},
{"a max age that is no duration", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"max-age":"a day"}],"events":`, 1), "accepts[0].max-age"},
{"a negative max-msgs", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"max-msgs":-1}],"events":`, 1), "accepts[0].max-msgs"},
{"an event on a stream", strings.Replace(whole, `"name":"created"`, `"name":"created","stream":"check"`, 1), "only an accepted kind rides a stream"}, {"an event on a stream", strings.Replace(whole, `"name":"created"`, `"name":"created","stream":"check"`, 1), "only an accepted kind rides a stream"},
{"over 256 KiB", listGrain[:len(listGrain)-1] + `,"description":"` + strings.Repeat("x", MaxSize) + `"}`, {"over 256 KiB", listGrain[:len(listGrain)-1] + `,"description":"` + strings.Repeat("x", MaxSize) + `"}`,
ErrTooLarge.Error()}, ErrTooLarge.Error()},
@@ -173,6 +177,35 @@ func TestADefinitionIsReadStrictlyNamingWhatIsWrong(t *testing.T) {
`"}`)); !errors.Is(err, ErrTooLarge) { `"}`)); !errors.Is(err, ErrTooLarge) {
t.Errorf("over 256 KiB is ErrTooLarge, got %v", err) t.Errorf("over 256 KiB is ErrTooLarge, got %v", err)
} }
// Design 47 H2 §780, H-A-352: a definition and a part carry their form; absent reads 1, below 1 is refused.
for _, c := range []struct {
raw string
form int
bad bool
}{
{whole, 1, false},
{strings.Replace(whole, `"seat":`, `"form":3,"seat":`, 1), 3, false},
{strings.Replace(whole, `"seat":`, `"form":-1,"seat":`, 1), 0, true},
} {
d, err := Parse([]byte(c.raw))
if c.bad != (err != nil) || (!c.bad && d.Form != c.form) || (c.bad && !strings.Contains(err.Error(), "form")) {
t.Errorf("a definition of form %d read as %d, %v", c.form, d.Form, err)
}
}
for _, c := range []struct {
raw string
form int
bad bool
}{
{`{"format":1,"part":"registry"}`, 1, false},
{`{"format":1,"form":2,"part":"registry"}`, 2, false},
{`{"format":1,"form":-2,"part":"registry"}`, 0, true},
} {
p, err := ParsePart([]byte(c.raw))
if c.bad != (err != nil) || (!c.bad && p.Form != c.form) {
t.Errorf("a part %s read as form %d, %v", c.raw, p.Form, err)
}
}
// A part is taken in whole, its verbs before the definition's own; a part not given, or a type defined twice, // A part is taken in whole, its verbs before the definition's own; a part not given, or a type defined twice,
// is refused. // is refused.
+148 -16
View File
@@ -5,7 +5,7 @@
"grain": "whole", "grain": "whole",
"domain": "Delivery", "domain": "Delivery",
"decision": "novox/hq ADR 0111", "decision": "novox/hq ADR 0111",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer.", "description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer.",
"delivers": "git", "delivers": "git",
"verbs": [ "verbs": [
{ {
@@ -48,6 +48,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what pull answers; error and error-kind alone when it fails" "description": "what pull answers; error and error-kind alone when it fails"
@@ -96,6 +104,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what branch answers; error and error-kind alone when it fails" "description": "what branch answers; error and error-kind alone when it fails"
@@ -126,6 +142,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails", "description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails",
@@ -171,9 +195,9 @@
"tags": { "tags": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "$ref": "#/defs/Tag"
}, },
"description": "the tags of this page" "description": "the tags of this page, each with the commit it names (design 47 H2 §796)"
}, },
"page": { "page": {
"type": "integer", "type": "integer",
@@ -193,6 +217,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what tags answers; error and error-kind alone when it fails" "description": "what tags answers; error and error-kind alone when it fails"
@@ -201,7 +233,7 @@
}, },
{ {
"name": "trees", "name": "trees",
"description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part.", "description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part. A directory named in files or paths that the commit does not hold answers the error kind not-found (design 47 H2 §796).",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -284,6 +316,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what trees answers; error and error-kind alone when it fails" "description": "what trees answers; error and error-kind alone when it fails"
@@ -350,6 +390,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what file answers; error and error-kind alone when it fails" "description": "what file answers; error and error-kind alone when it fails"
@@ -410,6 +458,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what contains answers; error and error-kind alone when it fails" "description": "what contains answers; error and error-kind alone when it fails"
@@ -464,6 +520,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what statuses answers; error and error-kind alone when it fails" "description": "what statuses answers; error and error-kind alone when it fails"
@@ -546,6 +610,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what status answers; error and error-kind alone when it fails" "description": "what status answers; error and error-kind alone when it fails"
@@ -607,6 +679,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what comment answers; error and error-kind alone when it fails" "description": "what comment answers; error and error-kind alone when it fails"
@@ -668,6 +748,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what view answers; error and error-kind alone when it fails" "description": "what view answers; error and error-kind alone when it fails"
@@ -730,6 +818,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what note answers; error and error-kind alone when it fails" "description": "what note answers; error and error-kind alone when it fails"
@@ -738,7 +834,7 @@
}, },
{ {
"name": "merge-pull", "name": "merge-pull",
"description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H \u00a7734, \u00a7735, \u00a7766; ADR 0682 \u00a71, \u00a72). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.", "description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H §734, §735, §766; ADR 0682 §1, §2). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -805,6 +901,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what merge-pull answers at the call's end; error and error-kind alone when it fails" "description": "what merge-pull answers at the call's end; error and error-kind alone when it fails"
@@ -815,7 +919,7 @@
{ {
"name": "tag", "name": "tag",
"class": "act", "class": "act",
"description": "Write the git tag of a released version, go/vMAJOR.MINOR.PATCH, at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.", "description": "Write the git tag of a released version, <directory>/vMAJOR.MINOR.PATCH for a Go package (design 47 H2 §796), at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -856,6 +960,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what tag answers; error and error-kind alone when it fails" "description": "what tag answers; error and error-kind alone when it fails"
@@ -1259,7 +1371,7 @@
"name": "calls", "name": "calls",
"template": "state", "template": "state",
"history": 1, "history": 1,
"description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H \u00a7766, H-A-47)", "description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H §766, H-A-47)",
"key-forms": [ "key-forms": [
{ {
"key": "call.<call>", "key": "call.<call>",
@@ -1328,7 +1440,7 @@
"description": "its page on the forge" "description": "its page on the forge"
} }
}, },
"description": "one pull request as the forge holds it; never its description (ADR 0659 \u00a71)", "description": "one pull request as the forge holds it; never its description (ADR 0659 §1)",
"required": [ "required": [
"repository", "repository",
"number", "number",
@@ -1361,7 +1473,7 @@
"description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused" "description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused"
} }
}, },
"description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 \u00a71): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one", "description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 §1): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one",
"required": [ "required": [
"mergeable", "mergeable",
"protected", "protected",
@@ -1471,9 +1583,10 @@
"enum": [ "enum": [
"refused", "refused",
"not-found", "not-found",
"failed" "failed",
"away"
], ],
"description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed" "description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed; away, a part the holder depends on (the forge, its store) is away, with part naming what did not answer and words: a caller reads it as a transport fault and calls again (design 47 H2 §776)"
}, },
"FailedStep": { "FailedStep": {
"type": "object", "type": "object",
@@ -1529,7 +1642,7 @@
}, },
"MemberOutcome": { "MemberOutcome": {
"type": "object", "type": "object",
"description": "one member of a merge call and where it stands (design 47 H \u00a7766, H-A-22)", "description": "one member of a merge call and where it stands (design 47 H §766, H-A-22)",
"properties": { "properties": {
"repository": { "repository": {
"type": "string" "type": "string"
@@ -1564,7 +1677,7 @@
}, },
"Call": { "Call": {
"type": "object", "type": "object",
"description": "one merge call, written before its first merge and updated as each member merges (design 47 H \u00a7766)", "description": "one merge call, written before its first merge and updated as each member merges (design 47 H §766)",
"properties": { "properties": {
"by": { "by": {
"type": "string", "type": "string",
@@ -1640,12 +1753,30 @@
"head", "head",
"state" "state"
] ]
},
"Tag": {
"type": "object",
"description": "a tag and the commit it names (design 47 H2 §796)",
"properties": {
"tag": {
"type": "string"
},
"commit": {
"type": "string",
"description": "the commit it names, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"tag",
"commit"
]
} }
}, },
"bodies": { "bodies": {
"MergeCalled": { "MergeCalled": {
"type": "object", "type": "object",
"description": "a merge call's members merged or refused, said once by the forge module (design 47 H \u00a7736, \u00a7767)", "description": "a merge call's members merged or refused, said once by the forge module (design 47 H §736, §767)",
"properties": { "properties": {
"call": { "call": {
"type": "string", "type": "string",
@@ -1702,7 +1833,7 @@
}, },
"refused": { "refused": {
"type": "array", "type": "array",
"description": "one per member not merged after every member was judged (design 47 H \u00a7767)", "description": "one per member not merged after every member was judged (design 47 H §767)",
"items": { "items": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -1732,5 +1863,6 @@
"members" "members"
] ]
} }
} },
"form": 2
} }
+179 -9
View File
@@ -253,6 +253,49 @@
}, },
"class": "read" "class": "read"
}, },
{
"name": "seat-list",
"class": "read",
"description": "The trunk's seat list as the mesh holds it, the object of the holder's objects seat-lists of that digest (design 47 H2 §814, §820; H-A-441, H-A-443): its digest and size, then its bytes (the definitions resolved, a JSON array in the form of a composer request's seats, sorted by seat) in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds. A validate run's asker fills the request's seats from these bytes. Reads only.",
"input": {
"type": "object",
"properties": {
"call": {
"type": "string",
"description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements",
"minLength": 1
}
},
"required": [
"call"
]
},
"answer": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the seat list's sha256, the object's name in seat-lists"
},
"size": {
"type": "integer",
"minimum": 0,
"description": "the seat list's size in bytes"
},
"chunks": {
"type": "integer",
"minimum": 0,
"description": "how many chunks are sent"
}
},
"required": [
"digest",
"size",
"chunks"
]
},
"chunks": true
},
{ {
"name": "revision", "name": "revision",
"description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).", "description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).",
@@ -312,7 +355,7 @@
}, },
{ {
"name": "registrations", "name": "registrations",
"description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed.", "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed. Filtered by module or repository while it reads and paged by the cursor next, at most 768 KB a page (design 47 H2 §806, §811).",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -323,6 +366,14 @@
"history": { "history": {
"type": "boolean", "type": "boolean",
"description": "with every version of the one module" "description": "with every version of the one module"
},
"repository": {
"type": "string",
"description": "only the registrations of this repository, <owner>/<name>, applied while reading (design 47 H2 §806)"
},
"next": {
"type": "string",
"description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)"
} }
} }
}, },
@@ -344,6 +395,18 @@
}, },
"fill": { "fill": {
"$ref": "#/defs/Fill" "$ref": "#/defs/Fill"
},
"capped": {
"type": "boolean",
"description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §806)"
},
"total": {
"type": "integer",
"description": "how many registrations the filters hold in all (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)"
} }
}, },
"required": [ "required": [
@@ -657,6 +720,32 @@
"source": { "source": {
"type": "integer" "type": "integer"
}, },
"call": {
"type": "string",
"description": "what made the revision, as the revision's call names it (design 47 H-A-212, H-A-213); absent for a candidate's"
},
"call-kind": {
"type": "string",
"enum": [
"take-in",
"release",
"take-in-again",
"recompute"
],
"description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217); absent for a candidate's"
},
"module": {
"type": "string",
"description": "for call-kind release, the module released (H-A-215)"
},
"version": {
"type": "string",
"description": "for call-kind release, the version released (H-A-215)"
},
"repository": {
"type": "string",
"description": "for call-kind take-in-again, the repository taken in again (H-A-215)"
},
"group": { "group": {
"type": "string" "type": "string"
}, },
@@ -1448,6 +1537,13 @@
"$ref": "#/defs/Registration" "$ref": "#/defs/Registration"
}, },
"description": "a module's registration" "description": "a module's registration"
},
{
"key": "source.<owner>.<name>",
"value": {
"$ref": "#/defs/Registration"
},
"description": "a source-only registration of a repository with no module (design 47 H2 §815)"
} }
] ]
}, },
@@ -1462,6 +1558,13 @@
"$ref": "#/defs/Registration" "$ref": "#/defs/Registration"
}, },
"description": "one version of a module's registration" "description": "one version of a module's registration"
},
{
"key": "source.<owner>.<name>.<version>",
"value": {
"$ref": "#/defs/Registration"
},
"description": "one version of a source-only registration (design 47 H2 §815)"
} }
] ]
}, },
@@ -1594,6 +1697,10 @@
"type": "string", "type": "string",
"description": "its manifest's verdict: accepted, refused or held" "description": "its manifest's verdict: accepted, refused or held"
}, },
"class": {
"type": "string",
"description": "core or leaf: core when its manifest claims a seat, leaf when it claims none; an entry without it reads as leaf (design 47 H2 H-A-394, H-A-431)"
},
"fp": { "fp": {
"type": "string", "type": "string",
"description": "its fingerprint (src2: and 64 hex digits); absent when it has none" "description": "its fingerprint (src2: and 64 hex digits); absent when it has none"
@@ -1871,6 +1978,32 @@
"type": "integer", "type": "integer",
"description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto" "description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto"
}, },
"call": {
"type": "string",
"description": "what made the revision (design 47 H-A-212, H-A-213): a take-in's the gate's call its source revision names, a re-pin's release of <module> <version>, a take-in again's take-in again of <repository>; absent for a candidate's"
},
"call-kind": {
"type": "string",
"enum": [
"take-in",
"release",
"take-in-again",
"recompute"
],
"description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217): a take-in's, a re-pin's on a module's release, a take-in again's, a recompute's that moved a fingerprint (its call naming the reason); absent for a candidate's"
},
"module": {
"type": "string",
"description": "for call-kind release, the module released (H-A-215)"
},
"version": {
"type": "string",
"description": "for call-kind release, the version released (H-A-215)"
},
"repository": {
"type": "string",
"description": "for call-kind take-in-again, the repository taken in again (H-A-215)"
},
"group": { "group": {
"type": "string", "type": "string",
"description": "a candidate's group" "description": "a candidate's group"
@@ -1927,6 +2060,10 @@
"$ref": "#/defs/TakeInEntry" "$ref": "#/defs/TakeInEntry"
}, },
"description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover" "description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover"
},
"base": {
"type": "integer",
"description": "the newest kept revision of its branch below it, which the take-in that wrote it pinned for its pipeline: the base of the validate step's case before (design 47 H-A-147, H-A-151, H-A-154); absent on the branch's first take-in"
} }
}, },
"required": [ "required": [
@@ -2078,14 +2215,15 @@
}, },
"Registration": { "Registration": {
"type": "object", "type": "object",
"description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve", "description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve; or a source-only registration of a repository with no module (design 47 H2 §815): its origin, one watched branch, its policy and its check, naming no module and no path, kept under source.<owner>.<name>",
"properties": { "properties": {
"v": { "v": {
"type": "integer", "type": "integer",
"description": "the layout version" "description": "the layout version"
}, },
"module": { "module": {
"type": "string" "type": "string",
"description": "the module; absent for a source-only registration"
}, },
"origin": { "origin": {
"type": "string", "type": "string",
@@ -2093,7 +2231,7 @@
}, },
"path": { "path": {
"type": "string", "type": "string",
"description": "the path of its manifest in the repository" "description": "the path of its manifest in the repository; absent for a source-only registration"
}, },
"branches": { "branches": {
"type": "array", "type": "array",
@@ -2121,12 +2259,14 @@
"at": { "at": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time"
},
"check": {
"$ref": "#/defs/SourceCheck",
"description": "for a source-only registration, the one step its heads run (design 47 H2 §815)"
} }
}, },
"required": [ "required": [
"module",
"origin", "origin",
"path",
"branches", "branches",
"policy" "policy"
] ]
@@ -2157,9 +2297,10 @@
"placed", "placed",
"review required", "review required",
"unknown module", "unknown module",
"nothing moves" "nothing moves",
"holds-manifest"
], ],
"description": "why no ask was raised" "description": "why no ask was raised; holds-manifest: a source-only registration whose repository holds a module.json at its root or under modules/ at the branch's head (design 47 H2 §815; H-A-450)"
}, },
"words": { "words": {
"type": "string", "type": "string",
@@ -2469,6 +2610,34 @@
"ref", "ref",
"language" "language"
] ]
},
"SourceCheck": {
"type": "object",
"description": "the check of a source-only registration: a build seat and a step kind, run at the repository's root, never a free command (design 47 H2 §815)",
"properties": {
"seat": {
"type": "string",
"enum": [
"node-build-go",
"node-build-node",
"node-build-image"
],
"description": "the build seat that runs it"
},
"step": {
"type": "string",
"enum": [
"lint",
"unit",
"integration"
],
"description": "the step kind"
}
},
"required": [
"seat",
"step"
]
} }
}, },
"bodies": { "bodies": {
@@ -2567,5 +2736,6 @@
"call" "call"
] ]
} }
} },
"form": 5
} }
+55 -8
View File
@@ -9,7 +9,7 @@
"verbs": [ "verbs": [
{ {
"name": "deliveries", "name": "deliveries",
"description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group.", "description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group. Filtered by repository, module, outcome and since while it reads, at most 768 KB a page, capped saying the rest is read from the cursor next (design 47 H2 §811).",
"input": { "input": {
"properties": { "properties": {
"all": { "all": {
@@ -31,13 +31,55 @@
"state": { "state": {
"description": "one state, e.g. delivering or held", "description": "one state, e.g. delivering or held",
"type": "string" "type": "string"
},
"module": {
"type": "string",
"description": "only the deliveries that move this module, applied while reading (design 47 H2 §811)"
},
"outcome": {
"type": "string",
"description": "only the deliveries that ended with this outcome, applied while reading (design 47 H2 §811)"
},
"since": {
"type": "string",
"format": "date-time",
"description": "only the deliveries opened at or after this time, applied while reading (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)"
} }
}, },
"type": "object" "type": "object"
}, },
"answer": { "answer": {
"type": "object", "type": "object",
"description": "what deliveries answers, as its description says" "description": "what deliveries answers, as its description says",
"properties": {
"deliveries": {
"type": "array",
"items": {
"type": "object",
"description": "one delivery's record, as the gate keeps it"
},
"description": "this page's deliveries, the open ones first, then the newest"
},
"capped": {
"type": "boolean",
"description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811)"
},
"total": {
"type": "integer",
"description": "how many deliveries the filters hold in all (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)"
}
},
"required": [
"deliveries"
]
}, },
"class": "read" "class": "read"
}, },
@@ -196,7 +238,7 @@
"name": "record-opened", "name": "record-opened",
"body": { "body": {
"type": "object", "type": "object",
"description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)", "description": "a delivery record opened for one source revision of a merge call (design 47 H §737)",
"properties": { "properties": {
"record": { "record": {
"type": "string", "type": "string",
@@ -319,7 +361,7 @@
"subject": "source-moved.<branch>.<source>", "subject": "source-moved.<branch>.<source>",
"body": { "body": {
"type": "object", "type": "object",
"description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)", "description": "a source revision of a watched branch, named once per merge call (design 47 H §737)",
"properties": { "properties": {
"v": { "v": {
"type": "integer" "type": "integer"
@@ -337,7 +379,7 @@
}, },
"start": { "start": {
"type": "boolean", "type": "boolean",
"description": "true only for a branch's first revision (design 47 H \u00a7768)" "description": "true only for a branch's first revision (design 47 H §768)"
}, },
"heads": { "heads": {
"type": "array", "type": "array",
@@ -448,7 +490,7 @@
}, },
"call": { "call": {
"type": "string", "type": "string",
"description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)" "description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H §737, H-A-33)"
} }
}, },
"required": [ "required": [
@@ -512,7 +554,7 @@
"name": "heads", "name": "heads",
"template": "state", "template": "state",
"history": 1, "history": 1,
"description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H \u00a7740)", "description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H §740)",
"key-forms": [ "key-forms": [
{ {
"key": "<repository>.<branch>", "key": "<repository>.<branch>",
@@ -607,6 +649,10 @@
"type": "string", "type": "string",
"format": "date-time", "format": "date-time",
"description": "when the gate first said it" "description": "when the gate first said it"
},
"record": {
"type": "string",
"description": "the delivery record the act is for, by its source revision, <branch>.<source>; absent on an act said before it was named, which bridge_owed_again by record never finds (design 47 H2 §807, H-A-432)"
} }
}, },
"required": [ "required": [
@@ -672,5 +718,6 @@
"head" "head"
] ]
} }
} },
"form": 2
} }
+233 -24
View File
@@ -1,11 +1,12 @@
{ {
"format": 1, "format": 1,
"form": 4,
"seat": "node-engine", "seat": "node-engine",
"scope": "node", "scope": "node",
"grain": "whole", "grain": "whole",
"domain": "Core", "domain": "Core",
"decision": "novox/hq ADR 0563", "decision": "novox/hq ADR 0563",
"description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token, or, for an event whose subject names <node>, there (composed.<node>, running.<node>.<module>): the grants part grants a node's account only its own node's subjects (ADR 0363 §2).", "description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 \u00a73, \u00a74): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token, or, for an event whose subject names <node>, there (composed.<node>, running.<node>.<module>): the grants part grants a node's account only its own node's subjects (ADR 0363 \u00a72).",
"acts": [ "acts": [
{ {
"step": "compose", "step": "compose",
@@ -15,7 +16,7 @@
"verbs": [ "verbs": [
{ {
"name": "hand-over", "name": "hand-over",
"description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 §3, §5): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.", "description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 \u00a73, \u00a75): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.",
"input": { "input": {
"properties": { "properties": {
"path": { "path": {
@@ -39,7 +40,7 @@
}, },
{ {
"name": "access-act", "name": "access-act",
"description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 §7, ADR 0563 §3, §4), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 \u00a77, ADR 0563 \u00a73, \u00a74), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.",
"input": { "input": {
"properties": { "properties": {
"access": { "access": {
@@ -68,7 +69,7 @@
}, },
{ {
"name": "judge-directories", "name": "judge-directories",
"description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 §2). Read-only: changes no owner or mode.", "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 \u00a72). Read-only: changes no owner or mode.",
"input": { "input": {
"properties": {}, "properties": {},
"type": "object" "type": "object"
@@ -80,7 +81,7 @@
}, },
{ {
"name": "setuid-search", "name": "setuid-search",
"description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 §2); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 \u00a72); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.",
"input": { "input": {
"properties": { "properties": {
"why": { "why": {
@@ -97,7 +98,7 @@
}, },
{ {
"name": "root-free", "name": "root-free",
"description": "Whether this machine is root-free (novox/hq ADR 0259 §8, ADR 0563 §6): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", "description": "Whether this machine is root-free (novox/hq ADR 0259 \u00a78, ADR 0563 \u00a76): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.",
"input": { "input": {
"properties": {}, "properties": {},
"type": "object" "type": "object"
@@ -121,7 +122,7 @@
}, },
{ {
"name": "acts", "name": "acts",
"description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 §9): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 \u00a79): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.",
"input": { "input": {
"properties": { "properties": {
"id": { "id": {
@@ -242,7 +243,7 @@
"type": "string" "type": "string"
}, },
"digest": { "digest": {
"description": "a composition's digest (sha256:…), to read that revision rather than the latest", "description": "a composition's digest (sha256:\u2026), to read that revision rather than the latest",
"type": "string" "type": "string"
}, },
"module": { "module": {
@@ -287,7 +288,7 @@
}, },
"self": { "self": {
"type": "boolean", "type": "boolean",
"description": "the node composes the module itself (ADR 0547 §2)" "description": "the node composes the module itself (ADR 0547 \u00a72)"
}, },
"backup": { "backup": {
"type": "string", "type": "string",
@@ -455,6 +456,32 @@
}, },
"description": "every resource that differs from what runs, when asked" "description": "every resource that differs from what runs, when asked"
}, },
"drift": {
"type": "array",
"description": "when the diff is asked, each directory entry of what runs that the mesh made, as its record holds, whose owner or mode on disk differ from it (H-A-392 (b), H-A-458 (2)): read-only; the engine sets it right at its next start or apply of the module",
"items": {
"type": "object",
"required": [
"id",
"path",
"drift"
],
"properties": {
"id": {
"type": "string",
"description": "the directory entry's id in the composition"
},
"path": {
"type": "string",
"description": "its path on the machine"
},
"drift": {
"type": "string",
"description": "how its owner or mode on disk differ, in words"
}
}
}
},
"own": { "own": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -517,6 +544,27 @@
"withheld-unknown": { "withheld-unknown": {
"type": "string", "type": "string",
"description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer" "description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer"
},
"withheld-parts": {
"type": "array",
"description": "each part a compose kept because its read did not answer, with why (design 08 control-verbs \u00a74, H-A-321): for the packet filter's holder the part node-packet-filter.allowed, its filter file kept as it runs",
"items": {
"type": "object",
"required": [
"part",
"why"
],
"properties": {
"part": {
"type": "string",
"description": "the read asked, as <seat>.<verb>"
},
"why": {
"type": "string",
"description": "why it did not answer, naming the holder asked"
}
}
}
} }
}, },
"required": [ "required": [
@@ -529,6 +577,63 @@
}, },
"class": "read" "class": "read"
}, },
{
"name": "composition-diff",
"description": "One module's composed values read by resource (design 47 H2 \u00a7813 (3), H-A-349 DQ-12b): given a module and a revision or a digest of its composition, the entries that differ between the composition that runs and that one, per resource, environment entries by name, a secret's value masked. Read-only. Answered by this machine's engine alone.",
"class": "read",
"input": {
"type": "object",
"required": [
"module"
],
"properties": {
"module": {
"type": "string",
"description": "the module, as placed on this machine; node for the node's own"
},
"revision": {
"type": "integer",
"description": "the revision of the module's composition key to compare with, from the revisions the bucket keeps; give it or digest"
},
"digest": {
"type": "string",
"description": "the digest (sha256:\u2026) of the composition to compare with; give it or revision"
}
}
},
"answer": {
"type": "object",
"required": [
"node",
"module",
"resources"
],
"properties": {
"node": {
"type": "string",
"description": "the node"
},
"module": {
"type": "string",
"description": "the module"
},
"running": {
"type": "string",
"description": "the digest of the composition that runs; absent when nothing runs"
},
"other": {
"$ref": "#/defs/Revision"
},
"resources": {
"type": "array",
"description": "each resource with an entry that differs; empty when none differs",
"items": {
"$ref": "#/defs/CompositionDiffResource"
}
}
}
}
},
{ {
"name": "compose", "name": "compose",
"description": "Compose this machine's modules now and say how it went, so a composition that failed, or a module held, recovers without a restart: what the pass refused or held, each with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried again. Changes only what a pass the engine makes on its own would change.", "description": "Compose this machine's modules now and say how it went, so a composition that failed, or a module held, recovers without a restart: what the pass refused or held, each with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried again. Changes only what a pass the engine makes on its own would change.",
@@ -595,7 +700,7 @@
}, },
{ {
"name": "compose-candidate", "name": "compose-candidate",
"description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 §7). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.", "description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 \u00a77). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.",
"optional": true, "optional": true,
"input": { "input": {
"properties": { "properties": {
@@ -640,7 +745,7 @@
"unready", "unready",
"not-judged" "not-judged"
], ],
"description": "the node's verdict (ADR 0593 §7, §9)" "description": "the node's verdict (ADR 0593 \u00a77, \u00a79)"
}, },
"modules": { "modules": {
"type": "array", "type": "array",
@@ -686,7 +791,7 @@
{ {
"name": "manifest-reads", "name": "manifest-reads",
"optional": true, "optional": true,
"description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 §3) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.", "description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 \u00a73) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.",
"input": { "input": {
"type": "object", "type": "object",
"properties": {} "properties": {}
@@ -720,7 +825,7 @@
"node", "node",
"stated-at" "stated-at"
], ],
"description": "what this machine's engine reads of a manifest (ADR 0618 §3)" "description": "what this machine's engine reads of a manifest (ADR 0618 \u00a73)"
}, },
"class": "read" "class": "read"
}, },
@@ -787,7 +892,7 @@
}, },
{ {
"name": "seat-list", "name": "seat-list",
"description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 \u00a77): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.",
"input": { "input": {
"type": "object", "type": "object",
"properties": {} "properties": {}
@@ -798,7 +903,7 @@
}, },
{ {
"name": "seat-list-again", "name": "seat-list-again",
"description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 \u00a77), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.",
"input": { "input": {
"type": "object", "type": "object",
"properties": {} "properties": {}
@@ -1057,6 +1162,52 @@
"$ref": "#/defs/ProcessBuilds" "$ref": "#/defs/ProcessBuilds"
}, },
"class": "read" "class": "read"
},
{
"name": "converged",
"description": "The node's convergence state, which the node-engine keeps (ADR 0168, ADR 0683; design 33 control-verbs \u00a710): adopted or converged, since when it became so, for an adopted node the kind of the firewall found, and the node's links as the engine classifies them: the tunnel's interface and the outward links (design 47 H-A-325). Read-only: the holder of node-packet-filter asks it at its start and at every allow and disallow, and refuses when it does not answer.",
"class": "read",
"input": {
"type": "object",
"properties": {}
},
"answer": {
"type": "object",
"required": [
"state",
"tunnel",
"outward"
],
"properties": {
"state": {
"type": "string",
"enum": [
"adopted",
"converged"
],
"description": "the node's mode: adopted (the found firewall's terms) or converged (the mesh's own filter)"
},
"since": {
"type": "string",
"description": "when the node became so, RFC 3339; absent where the engine recorded no time for it"
},
"found": {
"type": "string",
"description": "the kind of the firewall found, for an adopted node"
},
"tunnel": {
"type": "string",
"description": "the private network's tunnel interface on this node, as the engine's filter render names it"
},
"outward": {
"type": "array",
"items": {
"type": "string"
},
"description": "the links of this node that face outside, as the engine classifies them for its filter render (ADR 0140); an allowance with no interface never opens one"
}
}
}
} }
], ],
"events": [ "events": [
@@ -1205,6 +1356,14 @@
"type": "boolean", "type": "boolean",
"description": "the move changes the build alone" "description": "the move changes the build alone"
}, },
"run": {
"type": "string",
"description": "the composition run's pipeline sequence, in decimal, the module was applied from (design 47 H2 §813 (1), H-A-388): a restarted engine applies no older run again"
},
"pipeline": {
"type": "string",
"description": "the pipeline of the want the module was applied from, its key <branch>.<source>, beside its run (H-A-429 (1), H-A-458 (1)): a want's run is compared with this run only when the want's branch is the same, the key without its last .<source>; absent for a want in none"
},
"kept": { "kept": {
"type": "array", "type": "array",
"items": { "items": {
@@ -1696,7 +1855,7 @@
"description": "one finding of the observer that wrote it" "description": "one finding of the observer that wrote it"
} }
], ],
"description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 §2, ADR 0636 §1); today `machine.<node>.seat-list-unread`" "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 \u00a72, ADR 0636 \u00a71); today `machine.<node>.seat-list-unread`"
}, },
{ {
"name": "bounds", "name": "bounds",
@@ -1708,7 +1867,7 @@
"key": "<what>.<id>", "key": "<what>.<id>",
"value": { "value": {
"type": "object", "type": "object",
"description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G §560, A-77)", "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G \u00a7560, A-77)",
"properties": { "properties": {
"v": { "v": {
"type": "integer", "type": "integer",
@@ -1815,7 +1974,7 @@
}, },
"auto": { "auto": {
"type": "boolean", "type": "boolean",
"description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4)" "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 \u00a74)"
} }
}, },
"required": [ "required": [
@@ -1825,7 +1984,7 @@
"at", "at",
"state" "state"
], ],
"description": "one act asked through the seat, as acts reads it (ADR 0563 §9)" "description": "one act asked through the seat, as acts reads it (ADR 0563 \u00a79)"
}, },
"ActSaid": { "ActSaid": {
"type": "object", "type": "object",
@@ -1870,7 +2029,7 @@
"state", "state",
"node" "node"
], ],
"description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 §1)" "description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 \u00a71)"
}, },
"Acts": { "Acts": {
"type": "object", "type": "object",
@@ -1961,7 +2120,7 @@
"at", "at",
"why" "why"
], ],
"description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 §4)" "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 \u00a74)"
}, },
"Module": { "Module": {
"type": "object", "type": "object",
@@ -2061,7 +2220,7 @@
"why", "why",
"judged" "judged"
], ],
"description": "the engine's root-free verdict (ADR 0563 §6)" "description": "the engine's root-free verdict (ADR 0563 \u00a76)"
}, },
"Said": { "Said": {
"type": "object", "type": "object",
@@ -2106,7 +2265,7 @@
}, },
"SeatList": { "SeatList": {
"type": "object", "type": "object",
"description": "what an engine holds of the seat list (novox/hq ADR 0636 §7)", "description": "what an engine holds of the seat list (novox/hq ADR 0636 \u00a77)",
"properties": { "properties": {
"status": { "status": {
"type": "object", "type": "object",
@@ -2451,6 +2610,10 @@
"type": "string" "type": "string"
} }
}, },
"declaration-reads": {
"type": "integer",
"description": "the declaration Version its engine reads (design 47 H2 §813 (12), H-A-416 (2), H-A-419): the composer writes this node's declaration at the lower of its own Version and this one, 1 when none is stated"
},
"runner-capabilities": { "runner-capabilities": {
"type": "array", "type": "array",
"items": { "items": {
@@ -3160,7 +3323,7 @@
}, },
"Running": { "Running": {
"type": "object", "type": "object",
"description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit", "description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 \u00a72), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit",
"properties": { "properties": {
"v": { "v": {
"type": "integer", "type": "integer",
@@ -3331,6 +3494,52 @@
"step", "step",
"since" "since"
] ]
},
"CompositionDiffEntry": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "the entry: an environment entry by its name, else the part of the resource that differs"
},
"running": {
"type": "string",
"description": "its value in the running composition; absent where the running one lacks it or the value is a secret"
},
"other": {
"type": "string",
"description": "its value in the other composition; absent where the other lacks it or the value is a secret"
},
"masked": {
"type": "boolean",
"description": "the value is a secret, so neither value is given"
}
},
"description": "one entry that differs between the running composition and the other"
},
"CompositionDiffResource": {
"type": "object",
"required": [
"resource",
"entries"
],
"properties": {
"resource": {
"type": "string",
"description": "the resource, as the composition names it"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/CompositionDiffEntry"
},
"description": "the entries of the resource that differ"
}
},
"description": "one resource with the entries of it that differ"
} }
} }
} }
+7
View File
@@ -370,6 +370,13 @@ func TestTheBootstrapEqualsTheTestsSeatList(t *testing.T) {
t.Errorf("%s: bootstrap/%s.json differs from seatlisttest/seats/%s.json", b.Seat, b.Seat, b.Seat) t.Errorf("%s: bootstrap/%s.json differs from seatlisttest/seats/%s.json", b.Seat, b.Seat, b.Seat)
} }
} }
// Design 47 H2, H-A-452: the tests' seat list holds the seats the live list holds, the recovery seat among them, so a
// test judges a manifest against the seats the running validator judges it against.
for _, seat := range []string{"mesh-builds", "mesh-delivery-view", "mesh-grants", "mesh-pipeline-runner", "mesh-recovery"} {
if _, ok := tests[seat]; !ok {
t.Errorf("seatlisttest holds no definition of %s", seat)
}
}
} }
// A host whose path for the seat's events became live after the seat spoke reads the list at once, once: a read // A host whose path for the seat's events became live after the seat spoke reads the list at once, once: a read
File diff suppressed because it is too large Load Diff
+1 -1
View File
@@ -193,7 +193,7 @@
}, },
{ {
"name": "remove", "name": "remove",
"description": "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base by the artifact sweep's holder. Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry.", "description": "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base, which the artifact sweep's holder asks; the caller is not judged (design 47 H2 §813 (7)). Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry.",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
+148 -16
View File
@@ -5,7 +5,7 @@
"grain": "whole", "grain": "whole",
"domain": "Delivery", "domain": "Delivery",
"decision": "novox/hq ADR 0111", "decision": "novox/hq ADR 0111",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer.", "description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer.",
"delivers": "git", "delivers": "git",
"verbs": [ "verbs": [
{ {
@@ -48,6 +48,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what pull answers; error and error-kind alone when it fails" "description": "what pull answers; error and error-kind alone when it fails"
@@ -96,6 +104,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what branch answers; error and error-kind alone when it fails" "description": "what branch answers; error and error-kind alone when it fails"
@@ -126,6 +142,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails", "description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails",
@@ -171,9 +195,9 @@
"tags": { "tags": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "$ref": "#/defs/Tag"
}, },
"description": "the tags of this page" "description": "the tags of this page, each with the commit it names (design 47 H2 §796)"
}, },
"page": { "page": {
"type": "integer", "type": "integer",
@@ -193,6 +217,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what tags answers; error and error-kind alone when it fails" "description": "what tags answers; error and error-kind alone when it fails"
@@ -201,7 +233,7 @@
}, },
{ {
"name": "trees", "name": "trees",
"description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part.", "description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part. A directory named in files or paths that the commit does not hold answers the error kind not-found (design 47 H2 §796).",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -284,6 +316,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what trees answers; error and error-kind alone when it fails" "description": "what trees answers; error and error-kind alone when it fails"
@@ -350,6 +390,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what file answers; error and error-kind alone when it fails" "description": "what file answers; error and error-kind alone when it fails"
@@ -410,6 +458,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what contains answers; error and error-kind alone when it fails" "description": "what contains answers; error and error-kind alone when it fails"
@@ -464,6 +520,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what statuses answers; error and error-kind alone when it fails" "description": "what statuses answers; error and error-kind alone when it fails"
@@ -546,6 +610,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what status answers; error and error-kind alone when it fails" "description": "what status answers; error and error-kind alone when it fails"
@@ -607,6 +679,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what comment answers; error and error-kind alone when it fails" "description": "what comment answers; error and error-kind alone when it fails"
@@ -668,6 +748,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what view answers; error and error-kind alone when it fails" "description": "what view answers; error and error-kind alone when it fails"
@@ -730,6 +818,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what note answers; error and error-kind alone when it fails" "description": "what note answers; error and error-kind alone when it fails"
@@ -738,7 +834,7 @@
}, },
{ {
"name": "merge-pull", "name": "merge-pull",
"description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H \u00a7734, \u00a7735, \u00a7766; ADR 0682 \u00a71, \u00a72). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.", "description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H §734, §735, §766; ADR 0682 §1, §2). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -805,6 +901,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what merge-pull answers at the call's end; error and error-kind alone when it fails" "description": "what merge-pull answers at the call's end; error and error-kind alone when it fails"
@@ -815,7 +919,7 @@
{ {
"name": "tag", "name": "tag",
"class": "act", "class": "act",
"description": "Write the git tag of a released version, go/vMAJOR.MINOR.PATCH, at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.", "description": "Write the git tag of a released version, <directory>/vMAJOR.MINOR.PATCH for a Go package (design 47 H2 §796), at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -856,6 +960,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what tag answers; error and error-kind alone when it fails" "description": "what tag answers; error and error-kind alone when it fails"
@@ -1259,7 +1371,7 @@
"name": "calls", "name": "calls",
"template": "state", "template": "state",
"history": 1, "history": 1,
"description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H \u00a7766, H-A-47)", "description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H §766, H-A-47)",
"key-forms": [ "key-forms": [
{ {
"key": "call.<call>", "key": "call.<call>",
@@ -1328,7 +1440,7 @@
"description": "its page on the forge" "description": "its page on the forge"
} }
}, },
"description": "one pull request as the forge holds it; never its description (ADR 0659 \u00a71)", "description": "one pull request as the forge holds it; never its description (ADR 0659 §1)",
"required": [ "required": [
"repository", "repository",
"number", "number",
@@ -1361,7 +1473,7 @@
"description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused" "description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused"
} }
}, },
"description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 \u00a71): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one", "description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 §1): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one",
"required": [ "required": [
"mergeable", "mergeable",
"protected", "protected",
@@ -1471,9 +1583,10 @@
"enum": [ "enum": [
"refused", "refused",
"not-found", "not-found",
"failed" "failed",
"away"
], ],
"description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed" "description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed; away, a part the holder depends on (the forge, its store) is away, with part naming what did not answer and words: a caller reads it as a transport fault and calls again (design 47 H2 §776)"
}, },
"FailedStep": { "FailedStep": {
"type": "object", "type": "object",
@@ -1529,7 +1642,7 @@
}, },
"MemberOutcome": { "MemberOutcome": {
"type": "object", "type": "object",
"description": "one member of a merge call and where it stands (design 47 H \u00a7766, H-A-22)", "description": "one member of a merge call and where it stands (design 47 H §766, H-A-22)",
"properties": { "properties": {
"repository": { "repository": {
"type": "string" "type": "string"
@@ -1564,7 +1677,7 @@
}, },
"Call": { "Call": {
"type": "object", "type": "object",
"description": "one merge call, written before its first merge and updated as each member merges (design 47 H \u00a7766)", "description": "one merge call, written before its first merge and updated as each member merges (design 47 H §766)",
"properties": { "properties": {
"by": { "by": {
"type": "string", "type": "string",
@@ -1640,12 +1753,30 @@
"head", "head",
"state" "state"
] ]
},
"Tag": {
"type": "object",
"description": "a tag and the commit it names (design 47 H2 §796)",
"properties": {
"tag": {
"type": "string"
},
"commit": {
"type": "string",
"description": "the commit it names, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"tag",
"commit"
]
} }
}, },
"bodies": { "bodies": {
"MergeCalled": { "MergeCalled": {
"type": "object", "type": "object",
"description": "a merge call's members merged or refused, said once by the forge module (design 47 H \u00a7736, \u00a7767)", "description": "a merge call's members merged or refused, said once by the forge module (design 47 H §736, §767)",
"properties": { "properties": {
"call": { "call": {
"type": "string", "type": "string",
@@ -1702,7 +1833,7 @@
}, },
"refused": { "refused": {
"type": "array", "type": "array",
"description": "one per member not merged after every member was judged (design 47 H \u00a7767)", "description": "one per member not merged after every member was judged (design 47 H §767)",
"items": { "items": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -1732,5 +1863,6 @@
"members" "members"
] ]
} }
} },
"form": 2
} }
@@ -0,0 +1,707 @@
{
"format": 1,
"seat": "mesh-builds",
"scope": "mesh",
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0666",
"description": "The builder's seat: it says each artifact it published and each agreed toolchain, and answers a module's reserved version. Held once for the mesh (design 47 G section 52, section 307).",
"verbs": [
{
"name": "reserved",
"class": "read",
"description": "A module's reserved version with each artifact's digest, for a registry holder deciding whether to publish; asked by the module or by a package's name in its ecosystem (design 47 G section 369, section 478; design 51, Publishing).",
"input": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module; give this or name"
},
"name": {
"type": "string",
"description": "a package's or an image's name in its ecosystem (the Go module path, the npm name, the image name), in place of module; a name no entry carries, or more than one entry carries, is answered error naming it (design 47 G section 478, section 491)"
},
"version": {
"type": "string",
"description": "the version, when asked for a particular one"
}
},
"required": []
},
"answer": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module"
},
"version": {
"type": "string",
"description": "the reserved version, MAJOR.MINOR.PATCH"
},
"artifacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"artifact": {
"type": "string",
"description": "the artifact reference, <module>:<artifact>"
},
"digest": {
"type": "string",
"description": "its digest once built; empty before"
}
},
"required": [
"artifact"
]
}
},
"released": {
"type": "boolean",
"description": "true when the version is released: the catalog holds it, and artifacts are the ones its release recorded with their digests; false when it is reserved (design 47 G 582, 679)"
},
"error": {
"type": "string",
"description": "a name no entry carries, or a version neither reserved nor released, naming which; set alone (design 47 G 582, 679)"
}
},
"description": "the reservation or release, or the error; module, version and artifacts are present whenever error is not (design 47 G 679)"
}
},
{
"name": "published",
"class": "read",
"description": "Whether an artifact built at a build fingerprint is published, from the builder's reservations and the registries' record, for the pipeline runner writing a mover's wait on a package: a package published before the wait was written is read, not waited for (design 47 H-A-326, H-A-328, H-A-274).",
"input": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module that builds the package"
},
"artifact": {
"type": "string",
"description": "the package's artifact reference, <module>:<artifact>"
},
"fingerprint": {
"type": "string",
"description": "the build fingerprint the package is built at, which the answer is matched by"
}
},
"required": [
"module",
"artifact",
"fingerprint"
]
},
"answer": {
"type": "object",
"properties": {
"published": {
"type": "boolean",
"description": "true when the artifact built at the fingerprint is published; a number a take-over withdrew is never published (design 47 H-A-331)"
},
"version": {
"type": "string",
"description": "the version it is published at, MAJOR.MINOR.PATCH, when published"
},
"digest": {
"type": "string",
"description": "the published artifact's digest, when published; absent for a release kept before the digest was kept (design 47 H-A-331)"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when the builder heard or confirmed the publish, when published; absent for a mark written before the publish time was kept (design 47 H-A-331)"
}
},
"required": [
"published"
]
}
},
{
"name": "drop",
"description": "End an ask on the seat's work queue for a caller that no longer waits for it (its step ended by its bound): one waiting is ended dropped when it is pulled, one taken is cancelled; both end the step could-not-run, its why naming the drop and who asked it, so no holder works on it after (design 47 H2 §778; H-A-401; ADR 0664 §4).",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the ask's id"
},
"by": {
"type": "string",
"description": "who drops it"
},
"why": {
"type": "string",
"description": "why the caller no longer waits"
}
},
"required": [
"id",
"why"
]
},
"answer": {
"type": "object",
"description": "whether the ask was held here"
},
"class": "act"
},
{
"name": "publish-queue",
"class": "read",
"description": "What the builder's work queue publishes holds, read by the builder from its own stream (design 47 H2 §793; H-A-454): the items' count per registry seat holder and class with the oldest and newest queue time, and the first 50 in the order they are pulled (the live class first, each class oldest first); module, and version, list only that module's items. A queue read past 4,000 items is answered capped, naming the items read and the queue's size.",
"input": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "list only this module's items"
},
"version": {
"type": "string",
"description": "with module: only this version's, MAJOR.MINOR.PATCH"
}
},
"required": []
},
"answer": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "how many items were read"
},
"counts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"holder": {
"type": "string",
"description": "the registry seat's holder"
},
"class": {
"type": "string",
"enum": [
"live",
"again"
],
"description": "the items' class"
},
"count": {
"type": "integer",
"description": "how many items of the class the holder's queue holds"
},
"oldest": {
"type": "string",
"format": "date-time",
"description": "when the oldest of them was queued"
},
"newest": {
"type": "string",
"format": "date-time",
"description": "when the newest of them was queued"
}
},
"required": [
"holder",
"class",
"count",
"oldest",
"newest"
]
},
"description": "per holder and class, sorted by holder, then class"
},
"queue": {
"type": "array",
"items": {
"type": "object",
"properties": {
"holder": {
"type": "string",
"description": "the registry seat's holder the item is sent to, a module"
},
"module": {
"type": "string",
"description": "the module whose version is published"
},
"version": {
"type": "string",
"description": "the reserved version, MAJOR.MINOR.PATCH"
},
"class": {
"type": "string",
"enum": [
"live",
"again"
],
"description": "live, a build a pipeline's step waits on, pulled first; again, asked again at a start"
},
"artifacts": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "each artifact reference, <module>:<artifact>, with the digest to publish"
},
"queued": {
"type": "string",
"format": "date-time",
"description": "when the item was put on the work queue"
}
},
"required": [
"holder",
"module",
"version",
"class",
"queued"
]
},
"description": "the first 50 items listed, per holder in the order they are pulled"
},
"listed": {
"type": "integer",
"description": "how many of total the answer lists"
},
"capped": {
"type": "boolean",
"description": "true when the queue held more items than were read; every count is then of the items read"
},
"items-read": {
"type": "integer",
"description": "with capped: how many items were read"
},
"queue-items": {
"type": "integer",
"description": "with capped: how many items the queue holds, from its stream's state"
},
"queue-bytes": {
"type": "integer",
"description": "with capped: the queue's size in bytes"
}
},
"required": [
"total",
"counts",
"queue",
"listed"
]
}
}
],
"accepts": [
{
"name": "step",
"body": {
"$ref": "#/defs/StepRun"
},
"max-age": "24h",
"max-msgs": 10000,
"ack-wait": "60s",
"in-progress": "20s",
"max-ack-pending": 1000,
"max-deliveries": 5,
"duplicates-window": "2m"
}
],
"events": [
{
"name": "package-published",
"keep": {
"max-age-days": 90,
"max-mib": 128
},
"body": {
"$ref": "#/defs/PackagePublished"
}
},
{
"name": "toolchain-agreed",
"keep": {
"max-age-days": 90,
"max-mib": 16
},
"body": {
"$ref": "#/defs/ToolchainAgreed"
}
},
{
"name": "step-ended",
"subject": "step-ended.<node>",
"body": {
"$ref": "#/defs/StepEnded"
},
"keep": {
"max-age-days": 90,
"max-mib": 32
}
},
{
"name": "ask-taken",
"subject": "ask-taken.<ask>",
"body": {
"type": "object",
"properties": {
"ask": {
"type": "string",
"description": "the ask's id"
},
"node": {
"type": "string",
"description": "the node whose holder took it"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when it was taken"
}
},
"required": [
"ask",
"node",
"at"
],
"description": "the seat's holder took the ask from the seat's work queue, at the pull: only the holder says it; the runner arms the ask's bound from it (design 47 H2 §777, §778)"
}
},
{
"name": "version-reserved",
"body": {
"type": "object",
"properties": {
"module": {
"type": "string"
},
"artifact": {
"type": "string"
},
"path": {
"type": "string",
"description": "the package's path"
},
"version": {
"type": "string"
},
"fingerprint": {
"type": "string"
},
"revision": {
"type": "string",
"description": "the catalog revision the reservation was made at"
}
},
"required": [
"module",
"artifact",
"path",
"version",
"fingerprint",
"revision"
],
"description": "the builder reserved a version for a module's artifact at a fingerprint: the indexer re-pins once, at the reservation (design 47 H2 §805)"
}
}
],
"family": {
"name": "mesh-builds.events",
"max-age-days": 7
},
"defs": {
"Dependency": {
"type": "object",
"properties": {
"part": {
"type": "string",
"description": "the dependency's part: for kind 1 the package's artifact reference, <module>:<artifact>; for kind 3 the agreed toolchain's part (design 47 G 466, 673)"
},
"kind": {
"type": "integer",
"enum": [
1,
3
],
"description": "1 an imported package, 3 the build toolchain (design 47 G section 374)"
},
"version": {
"type": "string",
"description": "the version of the dependency the build resolved"
},
"digest": {
"type": "string",
"description": "the digest of the part, as the build used it"
}
},
"required": [
"part",
"kind",
"version",
"digest"
],
"description": "a dependency the build resolved: one item of kind 1 for each resolved package and one of kind 3 for the toolchain, named by the build module in its step key and carried by the builder (design 47 G 374, 673)"
},
"PackagePublished": {
"type": "object",
"properties": {
"v": {
"type": "integer"
},
"artifact": {
"type": "string",
"description": "the package's artifact reference, <module>:<artifact>, from the catalog entry"
},
"module": {
"type": "string",
"description": "the module"
},
"version": {
"type": "string",
"description": "the version the build reserved, MAJOR.MINOR.PATCH"
},
"digest": {
"type": "string",
"description": "the published artifact's digest"
},
"branch": {
"type": "string",
"description": "the watched branch the build was made from"
},
"source": {
"type": "integer",
"description": "the source revision of that branch the build was made from"
},
"revision": {
"type": "integer",
"description": "the catalog revision number of that branch the build was made from, the indexer's count (design 47 H-A-218, H-A-220); absent from a reservation made before the field"
},
"dependencies": {
"type": "array",
"items": {
"$ref": "#/defs/Dependency"
},
"description": "each dependency the build resolved, with its version and digest"
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"v",
"artifact",
"module",
"version",
"digest",
"branch",
"source"
],
"description": "one artifact published at the module's reserved version (design 47 G section 52, section 334)"
},
"ToolchainAgreed": {
"type": "object",
"properties": {
"v": {
"type": "integer"
},
"language": {
"type": "string",
"description": "the language whose agreed toolchain changed"
},
"version": {
"type": "string",
"description": "the agreed toolchain's version"
},
"digests": {
"type": "array",
"description": "each digest the nodes reporting the agreed version report, as it stood when the version was agreed, with those nodes (design 47 G section 472, section 495)",
"items": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the toolchain part's digest"
},
"nodes": {
"type": "array",
"items": {
"type": "string"
},
"description": "the nodes reporting that digest"
}
},
"required": [
"digest",
"nodes"
]
}
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"v",
"language",
"version",
"digests"
],
"description": "the agreed toolchain of a language changed (design 47 G section 376, ADR 0584 section 1)"
},
"StepRun": {
"type": "object",
"description": "the build step of one module's pipeline (design 47 G section 230, A-97): the runner asks the seat mesh-builds to build a candidate's entries, each named by its fingerprint, and the builder, the one entry point for a candidate, takes the ask and answers the step's end",
"properties": {
"pipeline": {
"type": "string",
"description": "the runner's pipeline key, <branch>.<revision>.<module>, a branch escaped as a key's name is"
},
"step": {
"type": "string",
"enum": [
"build"
]
},
"branch": {
"type": "string",
"description": "the watched branch, or the branch of a run on request"
},
"revision": {
"type": "integer",
"description": "the catalog graph revision of the branch the pipeline runs for"
},
"source": {
"type": "integer",
"description": "the source revision of the watched branch; absent for a run on request"
},
"rerun": {
"type": "boolean",
"description": "the step is asked again by the runner's rerun"
},
"by": {
"type": "string",
"description": "for a rerun, the caller the runtime proved"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/BuildEntry"
},
"description": "each entry the candidate's build builds, by module and fingerprint"
}
},
"required": [
"pipeline",
"step",
"branch",
"entries"
]
},
"StepEnded": {
"type": "object",
"description": "the build step's end, said by the builder on the node it runs on (design 47 G A-97; ADR 0666 section 21): the runner takes it only from that holder's account, naming the ask and each entry's fingerprint it was asked at",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"id": {
"type": "string",
"description": "the ask's id"
},
"pipeline": {
"type": "string"
},
"step": {
"type": "string",
"enum": [
"build"
]
},
"node": {
"type": "string",
"description": "the node the builder ran it on, as in the subject"
},
"outcome": {
"type": "string",
"enum": [
"passed",
"failed",
"nothing to run",
"could not run"
],
"description": "never passed for a build that built nothing"
},
"said": {
"type": "string",
"description": "why it failed or could not run: the entry not built, the part not heard"
},
"rerun": {
"type": "boolean"
},
"by": {
"type": "string",
"description": "for a rerun, the caller the runtime proved"
},
"started": {
"type": "string",
"format": "date-time"
},
"ended": {
"type": "string",
"format": "date-time"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/BuildEntry"
},
"description": "each entry the step built, by module and fingerprint"
},
"packages": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "the pins the step's entries were built with, each mesh package's version by its module path, the ones the builder took from the registry for a package the entry named with none included; the runner asks the entry's held test steps with them (H-A-207)"
}
},
"required": [
"id",
"pipeline",
"step",
"node",
"outcome",
"entries"
]
},
"BuildEntry": {
"type": "object",
"description": "one entry a candidate's build builds: a module at the fingerprint of its build inputs, and the commit that fingerprint was read at",
"properties": {
"module": {
"type": "string"
},
"commit": {
"type": "string"
},
"fingerprint": {
"type": "string",
"description": "the module's build-input fingerprint at the commit"
}
},
"required": [
"module",
"fingerprint"
]
}
}
}
@@ -253,6 +253,49 @@
}, },
"class": "read" "class": "read"
}, },
{
"name": "seat-list",
"class": "read",
"description": "The trunk's seat list as the mesh holds it, the object of the holder's objects seat-lists of that digest (design 47 H2 §814, §820; H-A-441, H-A-443): its digest and size, then its bytes (the definitions resolved, a JSON array in the form of a composer request's seats, sorted by seat) in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds. A validate run's asker fills the request's seats from these bytes. Reads only.",
"input": {
"type": "object",
"properties": {
"call": {
"type": "string",
"description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements",
"minLength": 1
}
},
"required": [
"call"
]
},
"answer": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the seat list's sha256, the object's name in seat-lists"
},
"size": {
"type": "integer",
"minimum": 0,
"description": "the seat list's size in bytes"
},
"chunks": {
"type": "integer",
"minimum": 0,
"description": "how many chunks are sent"
}
},
"required": [
"digest",
"size",
"chunks"
]
},
"chunks": true
},
{ {
"name": "revision", "name": "revision",
"description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).", "description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).",
@@ -312,7 +355,7 @@
}, },
{ {
"name": "registrations", "name": "registrations",
"description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed.", "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed. Filtered by module or repository while it reads and paged by the cursor next, at most 768 KB a page (design 47 H2 §806, §811).",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -323,6 +366,14 @@
"history": { "history": {
"type": "boolean", "type": "boolean",
"description": "with every version of the one module" "description": "with every version of the one module"
},
"repository": {
"type": "string",
"description": "only the registrations of this repository, <owner>/<name>, applied while reading (design 47 H2 §806)"
},
"next": {
"type": "string",
"description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)"
} }
} }
}, },
@@ -344,6 +395,18 @@
}, },
"fill": { "fill": {
"$ref": "#/defs/Fill" "$ref": "#/defs/Fill"
},
"capped": {
"type": "boolean",
"description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §806)"
},
"total": {
"type": "integer",
"description": "how many registrations the filters hold in all (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)"
} }
}, },
"required": [ "required": [
@@ -657,6 +720,32 @@
"source": { "source": {
"type": "integer" "type": "integer"
}, },
"call": {
"type": "string",
"description": "what made the revision, as the revision's call names it (design 47 H-A-212, H-A-213); absent for a candidate's"
},
"call-kind": {
"type": "string",
"enum": [
"take-in",
"release",
"take-in-again",
"recompute"
],
"description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217); absent for a candidate's"
},
"module": {
"type": "string",
"description": "for call-kind release, the module released (H-A-215)"
},
"version": {
"type": "string",
"description": "for call-kind release, the version released (H-A-215)"
},
"repository": {
"type": "string",
"description": "for call-kind take-in-again, the repository taken in again (H-A-215)"
},
"group": { "group": {
"type": "string" "type": "string"
}, },
@@ -1448,6 +1537,13 @@
"$ref": "#/defs/Registration" "$ref": "#/defs/Registration"
}, },
"description": "a module's registration" "description": "a module's registration"
},
{
"key": "source.<owner>.<name>",
"value": {
"$ref": "#/defs/Registration"
},
"description": "a source-only registration of a repository with no module (design 47 H2 §815)"
} }
] ]
}, },
@@ -1462,6 +1558,13 @@
"$ref": "#/defs/Registration" "$ref": "#/defs/Registration"
}, },
"description": "one version of a module's registration" "description": "one version of a module's registration"
},
{
"key": "source.<owner>.<name>.<version>",
"value": {
"$ref": "#/defs/Registration"
},
"description": "one version of a source-only registration (design 47 H2 §815)"
} }
] ]
}, },
@@ -1594,6 +1697,10 @@
"type": "string", "type": "string",
"description": "its manifest's verdict: accepted, refused or held" "description": "its manifest's verdict: accepted, refused or held"
}, },
"class": {
"type": "string",
"description": "core or leaf: core when its manifest claims a seat, leaf when it claims none; an entry without it reads as leaf (design 47 H2 H-A-394, H-A-431)"
},
"fp": { "fp": {
"type": "string", "type": "string",
"description": "its fingerprint (src2: and 64 hex digits); absent when it has none" "description": "its fingerprint (src2: and 64 hex digits); absent when it has none"
@@ -1871,6 +1978,32 @@
"type": "integer", "type": "integer",
"description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto" "description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto"
}, },
"call": {
"type": "string",
"description": "what made the revision (design 47 H-A-212, H-A-213): a take-in's the gate's call its source revision names, a re-pin's release of <module> <version>, a take-in again's take-in again of <repository>; absent for a candidate's"
},
"call-kind": {
"type": "string",
"enum": [
"take-in",
"release",
"take-in-again",
"recompute"
],
"description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217): a take-in's, a re-pin's on a module's release, a take-in again's, a recompute's that moved a fingerprint (its call naming the reason); absent for a candidate's"
},
"module": {
"type": "string",
"description": "for call-kind release, the module released (H-A-215)"
},
"version": {
"type": "string",
"description": "for call-kind release, the version released (H-A-215)"
},
"repository": {
"type": "string",
"description": "for call-kind take-in-again, the repository taken in again (H-A-215)"
},
"group": { "group": {
"type": "string", "type": "string",
"description": "a candidate's group" "description": "a candidate's group"
@@ -1927,6 +2060,10 @@
"$ref": "#/defs/TakeInEntry" "$ref": "#/defs/TakeInEntry"
}, },
"description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover" "description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover"
},
"base": {
"type": "integer",
"description": "the newest kept revision of its branch below it, which the take-in that wrote it pinned for its pipeline: the base of the validate step's case before (design 47 H-A-147, H-A-151, H-A-154); absent on the branch's first take-in"
} }
}, },
"required": [ "required": [
@@ -2078,14 +2215,15 @@
}, },
"Registration": { "Registration": {
"type": "object", "type": "object",
"description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve", "description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve; or a source-only registration of a repository with no module (design 47 H2 §815): its origin, one watched branch, its policy and its check, naming no module and no path, kept under source.<owner>.<name>",
"properties": { "properties": {
"v": { "v": {
"type": "integer", "type": "integer",
"description": "the layout version" "description": "the layout version"
}, },
"module": { "module": {
"type": "string" "type": "string",
"description": "the module; absent for a source-only registration"
}, },
"origin": { "origin": {
"type": "string", "type": "string",
@@ -2093,7 +2231,7 @@
}, },
"path": { "path": {
"type": "string", "type": "string",
"description": "the path of its manifest in the repository" "description": "the path of its manifest in the repository; absent for a source-only registration"
}, },
"branches": { "branches": {
"type": "array", "type": "array",
@@ -2121,12 +2259,14 @@
"at": { "at": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time"
},
"check": {
"$ref": "#/defs/SourceCheck",
"description": "for a source-only registration, the one step its heads run (design 47 H2 §815)"
} }
}, },
"required": [ "required": [
"module",
"origin", "origin",
"path",
"branches", "branches",
"policy" "policy"
] ]
@@ -2157,9 +2297,10 @@
"placed", "placed",
"review required", "review required",
"unknown module", "unknown module",
"nothing moves" "nothing moves",
"holds-manifest"
], ],
"description": "why no ask was raised" "description": "why no ask was raised; holds-manifest: a source-only registration whose repository holds a module.json at its root or under modules/ at the branch's head (design 47 H2 §815; H-A-450)"
}, },
"words": { "words": {
"type": "string", "type": "string",
@@ -2469,6 +2610,34 @@
"ref", "ref",
"language" "language"
] ]
},
"SourceCheck": {
"type": "object",
"description": "the check of a source-only registration: a build seat and a step kind, run at the repository's root, never a free command (design 47 H2 §815)",
"properties": {
"seat": {
"type": "string",
"enum": [
"node-build-go",
"node-build-node",
"node-build-image"
],
"description": "the build seat that runs it"
},
"step": {
"type": "string",
"enum": [
"lint",
"unit",
"integration"
],
"description": "the step kind"
}
},
"required": [
"seat",
"step"
]
} }
}, },
"bodies": { "bodies": {
@@ -2567,5 +2736,6 @@
"call" "call"
] ]
} }
} },
"form": 5
} }
@@ -0,0 +1,96 @@
{
"format": 1,
"seat": "mesh-delivery-view",
"scope": "mesh",
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0540",
"description": "The status view of deliveries (ADR 0540): it serves no verb and says no seat event; its tools and its events delivered, moving, settled and stuck stay its holder's own, and it keeps the person's answers given in the web view.",
"states": [
{
"name": "answers",
"template": "state",
"view": true,
"history": 5,
"description": "the person's answer in the web view to an ask of the seat mesh-wants' state asks of a kind that needs no proof of who answered; only the holder writes a key, and only the holder deletes it, once the ask's key has left asks (design 47 G section 717)",
"key-forms": [
{
"key": "hold.<module>.<fingerprint>.view",
"value": {
"$ref": "#/defs/Answer"
},
"description": "the status view's answer to the ask of the seat mesh-wants' state asks under hold.<module>.<fingerprint> (design 47 G A-299)"
},
{
"key": "restore.<node>.<module>.<fingerprint>.view",
"value": {
"$ref": "#/defs/Answer"
},
"description": "the status view's answer to the ask of the seat mesh-wants' state asks under restore.<node>.<module>.<fingerprint> (design 47 G A-299)"
},
{
"key": "backup.<node>.<module>.<fingerprint>.view",
"value": {
"$ref": "#/defs/Answer"
},
"description": "the status view's answer to the ask of the seat mesh-wants' state asks under backup.<node>.<module>.<fingerprint> (design 47 G A-299)"
},
{
"key": "record.<node>.<module>.<digest>.view",
"value": {
"$ref": "#/defs/Answer"
},
"description": "the status view's answer to the ask of the seat mesh-wants' state asks under record.<node>.<module>.<digest> (design 47 G A-299)"
},
{
"key": "outside.<node>.<module>.<fingerprint>.view",
"value": {
"$ref": "#/defs/Answer"
},
"description": "the status view's answer to the ask of the seat mesh-wants' state asks under outside.<node>.<module>.<fingerprint> (design 47 G A-299)"
},
{
"key": "revert.<node>.<module>.<fingerprint>.view",
"value": {
"$ref": "#/defs/Answer"
},
"description": "the status view's answer to the ask of the seat mesh-wants' state asks under revert.<node>.<module>.<fingerprint> (design 47 G A-299)"
},
{
"key": "assignments.<proposal>.view",
"value": {
"$ref": "#/defs/Answer"
},
"description": "the status view's answer to the ask of the seat mesh-wants' state asks under assignments.<proposal> (design 47 G A-299)"
}
]
}
],
"defs": {
"Answer": {
"type": "object",
"description": "the status view's answer to an ask",
"properties": {
"v": {
"type": "integer"
},
"asking": {
"type": "string",
"description": "the asking it answers"
},
"option": {
"type": "string",
"description": "the option the person chose"
},
"words": {
"type": "string",
"description": "the person's words with it"
}
},
"required": [
"asking",
"option"
]
}
}
}
@@ -9,7 +9,7 @@
"verbs": [ "verbs": [
{ {
"name": "deliveries", "name": "deliveries",
"description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group.", "description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group. Filtered by repository, module, outcome and since while it reads, at most 768 KB a page, capped saying the rest is read from the cursor next (design 47 H2 §811).",
"input": { "input": {
"properties": { "properties": {
"all": { "all": {
@@ -31,13 +31,55 @@
"state": { "state": {
"description": "one state, e.g. delivering or held", "description": "one state, e.g. delivering or held",
"type": "string" "type": "string"
},
"module": {
"type": "string",
"description": "only the deliveries that move this module, applied while reading (design 47 H2 §811)"
},
"outcome": {
"type": "string",
"description": "only the deliveries that ended with this outcome, applied while reading (design 47 H2 §811)"
},
"since": {
"type": "string",
"format": "date-time",
"description": "only the deliveries opened at or after this time, applied while reading (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)"
} }
}, },
"type": "object" "type": "object"
}, },
"answer": { "answer": {
"type": "object", "type": "object",
"description": "what deliveries answers, as its description says" "description": "what deliveries answers, as its description says",
"properties": {
"deliveries": {
"type": "array",
"items": {
"type": "object",
"description": "one delivery's record, as the gate keeps it"
},
"description": "this page's deliveries, the open ones first, then the newest"
},
"capped": {
"type": "boolean",
"description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811)"
},
"total": {
"type": "integer",
"description": "how many deliveries the filters hold in all (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)"
}
},
"required": [
"deliveries"
]
}, },
"class": "read" "class": "read"
}, },
@@ -196,7 +238,7 @@
"name": "record-opened", "name": "record-opened",
"body": { "body": {
"type": "object", "type": "object",
"description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)", "description": "a delivery record opened for one source revision of a merge call (design 47 H §737)",
"properties": { "properties": {
"record": { "record": {
"type": "string", "type": "string",
@@ -319,7 +361,7 @@
"subject": "source-moved.<branch>.<source>", "subject": "source-moved.<branch>.<source>",
"body": { "body": {
"type": "object", "type": "object",
"description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)", "description": "a source revision of a watched branch, named once per merge call (design 47 H §737)",
"properties": { "properties": {
"v": { "v": {
"type": "integer" "type": "integer"
@@ -337,7 +379,7 @@
}, },
"start": { "start": {
"type": "boolean", "type": "boolean",
"description": "true only for a branch's first revision (design 47 H \u00a7768)" "description": "true only for a branch's first revision (design 47 H §768)"
}, },
"heads": { "heads": {
"type": "array", "type": "array",
@@ -448,7 +490,7 @@
}, },
"call": { "call": {
"type": "string", "type": "string",
"description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)" "description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H §737, H-A-33)"
} }
}, },
"required": [ "required": [
@@ -512,7 +554,7 @@
"name": "heads", "name": "heads",
"template": "state", "template": "state",
"history": 1, "history": 1,
"description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H \u00a7740)", "description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H §740)",
"key-forms": [ "key-forms": [
{ {
"key": "<repository>.<branch>", "key": "<repository>.<branch>",
@@ -607,6 +649,10 @@
"type": "string", "type": "string",
"format": "date-time", "format": "date-time",
"description": "when the gate first said it" "description": "when the gate first said it"
},
"record": {
"type": "string",
"description": "the delivery record the act is for, by its source revision, <branch>.<source>; absent on an act said before it was named, which bridge_owed_again by record never finds (design 47 H2 §807, H-A-432)"
} }
}, },
"required": [ "required": [
@@ -672,5 +718,6 @@
"head" "head"
] ]
} }
} },
"form": 2
} }
@@ -0,0 +1,293 @@
{
"format": 1,
"seat": "mesh-grants",
"scope": "mesh",
"grain": "whole",
"domain": "Identity and access",
"decision": "novox/hq ADR 0656, ADR 0547, ADR 0636",
"description": "Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441).",
"acts": [
{
"step": "grant",
"on": "every"
}
],
"verbs": [
{
"name": "grants-for",
"description": "The grants a candidate would compose, per module: the grants it would add and remove against the branch's newest, each named by its subject and verb. The candidate's catalog half is taken by mesh-catalog's revision (design 47 G 441).",
"class": "read",
"input": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "the candidate's source revision"
},
"run": {
"type": "string",
"description": "or the id of a run"
},
"branch": {
"type": "string",
"description": "its watched branch"
}
},
"required": [
"branch"
],
"additionalProperties": false
},
"answer": {
"$ref": "#/defs/GrantsFor"
}
},
{
"name": "withheld",
"description": "The marked subjects withheld from each module a node's runtime carries, and why: where its tool runner does not state approval-mark/1, or its reading is not the running runner's (design 46 approval mark 6).",
"class": "read",
"input": {
"type": "object",
"properties": {
"node": {
"type": "string",
"description": "the node whose runtime's withheld subjects are asked"
}
},
"required": [
"node"
],
"additionalProperties": false
},
"answer": {
"$ref": "#/defs/Withheld"
}
}
],
"events": [
{
"name": "wait-held",
"body": {
"$ref": "#/defs/Wait"
}
},
{
"name": "wait-ended",
"body": {
"$ref": "#/defs/Wait"
}
},
{
"name": "filling",
"body": {
"$ref": "#/defs/Fill"
}
},
{
"name": "room",
"body": {
"$ref": "#/defs/Fill"
}
}
],
"family": {
"name": "mesh-grants.events",
"max-age-days": 7
},
"defs": {
"Wait": {
"type": "object",
"description": "a granting wait the grants part holds: an entry whose grant waits until the grants part's new version runs (design 47 *Each step's wait is its own part's*)",
"properties": {
"step": {
"type": "string",
"description": "the step, grant",
"enum": [
"grant"
]
},
"part": {
"type": "string",
"description": "the acting part waited for"
},
"version": {
"type": "string",
"description": "its new version's fingerprint"
},
"module": {
"type": "string",
"description": "the entry that waits"
},
"fp": {
"type": "string",
"description": "the entry's fingerprint, whose grant waits"
},
"since": {
"type": "string",
"format": "date-time"
},
"bound": {
"type": "string",
"description": "a duration such as 10m"
},
"how": {
"type": "string",
"description": "on wait-ended: ran or released",
"enum": [
"ran",
"released"
]
},
"by": {
"type": "string",
"description": "on a release, who released it and why"
},
"clock-from": {
"type": "string",
"format": "date-time",
"description": "when the new version's build was done, as the builder's build.ended says; the bound's clock starts there (design 47 G 266)"
}
},
"required": [
"step",
"part",
"version",
"module",
"since",
"bound",
"clock-from"
]
},
"Fill": {
"type": "object",
"description": "a store's fill against its cap",
"properties": {
"store": {
"type": "string",
"description": "the store"
},
"bytes": {
"type": "integer"
},
"cap": {
"type": "integer",
"description": "bytes"
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"store",
"bytes",
"cap"
]
},
"Grant": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "the bus subject"
},
"verb": {
"type": "string",
"description": "the verb or event the grant is for"
}
},
"required": [
"subject",
"verb"
]
},
"GrantsFor": {
"type": "object",
"description": "the grants a candidate would compose, per module, added and removed against the branch's newest",
"properties": {
"modules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"module": {
"type": "string"
},
"added": {
"type": "array",
"items": {
"$ref": "#/defs/Grant"
}
},
"removed": {
"type": "array",
"items": {
"$ref": "#/defs/Grant"
}
}
},
"required": [
"module",
"added",
"removed"
]
}
},
"error": {
"type": "string",
"description": "why it could not be answered: the catalog half of the candidate is not held"
}
}
},
"Withheld": {
"type": "object",
"description": "a node's withheld subjects, by module",
"properties": {
"node": {
"type": "string"
},
"modules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"module": {
"type": "string"
},
"subjects": {
"type": "array",
"items": {
"$ref": "#/defs/WithheldSubject"
}
}
},
"required": [
"module",
"subjects"
]
}
}
},
"required": [
"node",
"modules"
]
},
"WithheldSubject": {
"type": "object",
"description": "one subject withheld, and why",
"properties": {
"subject": {
"type": "string"
},
"why": {
"type": "string"
}
},
"required": [
"subject",
"why"
]
}
}
}
@@ -135,6 +135,66 @@
"outcome" "outcome"
] ]
} }
},
{
"name": "attempt-changed",
"subject": "attempt-changed.<condition>.<attempt>",
"keep": {
"max-age-days": 7,
"max-mib": 16,
"last-per-subject": true
},
"body": {
"type": "object",
"description": "an attempt as the attempts state holds it, whole, with until, or removed: true when the healer ends it; said again for every open attempt at the healers' start (design 47 G 541, 665)",
"properties": {
"healer": {
"type": "string"
},
"condition": {
"type": "string"
},
"kind": {
"type": "string"
},
"budget-key": {
"type": "string",
"description": "what the budget counts by: the condition's key unless the healer says another"
},
"act": {
"type": "string"
},
"outcome": {
"type": "string",
"enum": [
"acting",
"acted",
"failed",
"escalated"
]
},
"said": {
"type": "string"
},
"begun": {
"type": "string",
"format": "date-time"
},
"finished": {
"type": "string",
"format": "date-time"
},
"until": {
"type": "string",
"format": "date-time",
"description": "the end of that key's lifetime, which the keeper drops the attempt at on its own clock"
},
"removed": {
"type": "boolean",
"description": "true when the healer ends the attempt"
}
}
}
} }
], ],
"family": { "family": {
@@ -154,6 +154,39 @@
"type": "object", "type": "object",
"description": "what was judged or asked again" "description": "what was judged or asked again"
} }
},
{
"name": "placement",
"description": "Read the placements of one module as the assignments rows hold them: for each watched branch a node runs it from, the nodes that run it from there.",
"optional": true,
"input": {
"properties": {
"module": {
"description": "the module",
"type": "string"
}
},
"required": [
"module"
],
"type": "object"
},
"answer": {
"properties": {
"placements": {
"type": "array",
"items": {
"$ref": "#/defs/ModulePlacement"
},
"description": "one per branch and build, the nodes that run the module from it"
}
},
"required": [
"placements"
],
"type": "object"
},
"class": "read"
} }
], ],
"events": [ "events": [
@@ -190,6 +223,7 @@
{ {
"name": "assignments", "name": "assignments",
"template": "state", "template": "state",
"view": true,
"key-forms": [ "key-forms": [
{ {
"key": "<node>.node", "key": "<node>.node",
@@ -316,6 +350,13 @@
"assignments": { "assignments": {
"$ref": "#/defs/Assignments", "$ref": "#/defs/Assignments",
"description": "the node's assignments with the proposal laid over it; absent when the proposal takes its key away" "description": "the node's assignments with the proposal laid over it; absent when the proposal takes its key away"
},
"added": {
"type": "object",
"additionalProperties": {
"$ref": "#/defs/AddedModule"
},
"description": "by module name, each module the candidate adds to this node without a want there: the `version` and `parts` the want it would write carries (design 47 G A-316); the node-engine builds such a module from this entry"
} }
}, },
"required": [ "required": [
@@ -364,6 +405,7 @@
{ {
"name": "seat-holders", "name": "seat-holders",
"template": "state", "template": "state",
"view": true,
"key-forms": [ "key-forms": [
{ {
"key": "<seat>", "key": "<seat>",
@@ -1007,6 +1049,46 @@
"scope", "scope",
"holders" "holders"
] ]
},
"ModulePlacement": {
"type": "object",
"description": "the nodes that run a module from one watched branch",
"properties": {
"branch": {
"type": "string"
},
"build": {
"type": "string",
"description": "the fingerprint of the build these nodes run from the branch; absent, the newest delivered of the branch (design 47 H 750, H-A-39): one row per branch and build"
},
"nodes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"branch",
"nodes"
]
},
"AddedModule": {
"type": "object",
"description": "what the want a candidate would write for a module carries of its build, in the want's own forms (the seat mesh-wants' state wants: `version` and `parts`; copied here because a seat definition cannot reuse another repository's seat's forms, design 47 G A-316)",
"properties": {
"version": {
"type": "string",
"description": "the module's released version, for people; none for a build of another watched branch (design 47 G section 379)"
},
"parts": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "the digest of each of the module's parts, by `<module>:<artifact>` (design 47 G section 379)"
}
}
} }
} }
} }
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+62 -1
View File
@@ -9,7 +9,7 @@
"verbs": [ "verbs": [
{ {
"name": "get", "name": "get",
"description": "One secret, sealed to the public key the asker sends (the sealed box of ADR 0206), with its generation; answered only to an asker the vault allows, as the bus proved it. Never the value in the clear, and never to a private key.", "description": "One secret, sealed to the public key the asker sends (the sealed box of ADR 0206), with its generation; answered only to an asker the vault allows, as the bus proved it, and a module's own secret put through own-put only to a process of the same module (design 47 H2 §822). Never the value in the clear, and never to a private key.",
"optional": true, "optional": true,
"input": { "input": {
"properties": { "properties": {
@@ -640,6 +640,67 @@
"required": [ "required": [
"retired" "retired"
] ]
},
"class": "act"
},
{
"name": "licence-put",
"description": "Hand the vault one of a licence's two secrets, its grant or its access token, from the licence manager, in two steps: name the licence by its key, the part and its generation and get a call and a key made for it; then send the call and the value sealed to that key. Keeps the newest generation and refuses an older one; says secret-changed with the secret's name and generation, never the value (novox/hq design 39 bus-and-switch §15).",
"optional": true,
"input": {
"properties": {
"call": {
"description": "the second step: the call the first step answered",
"type": "string"
},
"generation": {
"description": "the first step: the licence's generation",
"type": "number"
},
"licence": {
"description": "the first step: the licence's key",
"type": "string"
},
"part": {
"description": "the first step: grant or access",
"type": "string"
},
"sealed": {
"description": "the second step: the value sealed to the call's key — never the value",
"type": "string"
}
},
"type": "object"
},
"answer": {
"type": "object",
"description": "the holder's answer"
}
},
{
"name": "own-put",
"description": "Store a secret as the calling module's own, in two steps modelled on licence-put (design 47 H2 §822, H-A-345, H-A-349 DQ-7): name the secret and get a call and a key made for it (call, seal_to); then send the call and the value sealed to that key, and the vault keeps it under that name as the module's own, the module named by the caller's account as the bus proved it, never by an argument, keeping its newest generation only (name, generation). get answers it to a process of the same module, sealed to the process's key. The holder says each write in its journal without the value.",
"optional": true,
"input": {
"properties": {
"call": {
"description": "the second step: the call the first step answered",
"type": "string"
},
"name": {
"description": "the first step: the secret's name, among the calling module's own",
"type": "string"
},
"sealed": {
"description": "the second step: the value sealed to the call's key — never the value",
"type": "string"
}
},
"type": "object"
},
"answer": {
"type": "object",
"description": "the holder's answer: to the first step the call and the key to seal to (call, seal_to); to the second the secret's name and the generation kept (name, generation)"
} }
} }
], ],
+115 -4
View File
@@ -277,6 +277,66 @@
"run" "run"
] ]
} }
},
{
"name": "keep-now",
"description": "Keep the assignment graph's revisions now, by hand (design 47 H2 §813 (2); H-A-417): written in the hand-act log first by the module's tool assigner_keep_now, then the keeping runs at once on the pass's newest computed revision; answers the revision kept, or the fault the keeping met.",
"input": {
"type": "object",
"properties": {
"why": {
"type": "string",
"description": "why the keeping runs now"
}
},
"required": [
"why"
]
},
"answer": {
"type": "object",
"properties": {
"revision": {
"$ref": "#/defs/AssignmentRevision",
"description": "the revision kept"
},
"fault": {
"type": "string",
"description": "the fault the keeping met; absent when it kept the revision"
}
}
},
"class": "act"
},
{
"name": "drop",
"description": "End an ask on the seat's work queue for a caller that no longer waits for it (its step ended by its bound): one waiting is ended dropped when it is pulled, one taken is cancelled; both end the step could-not-run, its why naming the drop and who asked it, so no holder works on it after (design 47 H2 §778; ADR 0664 §4).",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the ask's id"
},
"by": {
"type": "string",
"description": "who drops it"
},
"why": {
"type": "string",
"description": "why the caller no longer waits"
}
},
"required": [
"id",
"why"
]
},
"answer": {
"type": "object",
"description": "whether the ask was held here"
},
"class": "act"
} }
], ],
"accepts": [ "accepts": [
@@ -284,7 +344,14 @@
"name": "step", "name": "step",
"body": { "body": {
"$ref": "#/defs/StepRun" "$ref": "#/defs/StepRun"
} },
"max-age": "24h",
"max-msgs": 10000,
"ack-wait": "60s",
"in-progress": "20s",
"max-ack-pending": 1000,
"max-deliveries": 5,
"duplicates-window": "2m"
} }
], ],
"events": [ "events": [
@@ -434,7 +501,7 @@
}, },
{ {
"name": "pipeline-wanted", "name": "pipeline-wanted",
"subject": "pipeline-wanted.<branch>.<source>", "subject": "pipeline-wanted.<branch>.<revision>",
"keep": { "keep": {
"max-age-days": 30, "max-age-days": 30,
"max-mib": 64 "max-mib": 64
@@ -525,6 +592,34 @@
"at" "at"
] ]
} }
},
{
"name": "ask-taken",
"subject": "ask-taken.<ask>",
"body": {
"type": "object",
"properties": {
"ask": {
"type": "string",
"description": "the ask's id"
},
"node": {
"type": "string",
"description": "the node whose holder took it"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when it was taken"
}
},
"required": [
"ask",
"node",
"at"
],
"description": "the seat's holder took the ask from the seat's work queue, at the pull: only the holder says it; the runner arms the ask's bound from it (design 47 H2 §777, §778)"
}
} }
], ],
"family": { "family": {
@@ -597,6 +692,10 @@
"type": "integer", "type": "integer",
"minimum": 1, "minimum": 1,
"description": "the mover's tier in that pipeline's delivery order, from 1; the node-engine applies one pipeline's wants by it; absent with pipeline (design 47 H §750, §771, H-A-37)" "description": "the mover's tier in that pipeline's delivery order, from 1; the node-engine applies one pipeline's wants by it; absent with pipeline (design 47 H §750, §771, H-A-37)"
},
"run": {
"type": "string",
"description": "the pipeline sequence of the composition run that wrote this want, in decimal: the holder writes by compare-and-set refusing a lower run, and the node-engine applies a want again only when its run is newer than the one it applied (design 47 H2 §813 (1); H-A-355 (1))"
} }
} }
}, },
@@ -1701,6 +1800,13 @@
"verdict": { "verdict": {
"type": "object", "type": "object",
"description": "that machine's composer verdict (design 47 G §721)" "description": "that machine's composer verdict (design 47 G §721)"
},
"unlisted": {
"type": "array",
"items": {
"type": "string"
},
"description": "the module names of the assignments left out of the machine's composition, those no watched branch's newest revision lists, written when the run starts and read by every step's judgement and by the resume (design 47 H-A-152, H-A-153)"
} }
}, },
"required": [ "required": [
@@ -1718,7 +1824,7 @@
}, },
"pipeline": { "pipeline": {
"type": "string", "type": "string",
"description": "the runner's pipeline key, <branch>.<source>, a branch escaped as a key's name is (design 47 H §746)" "description": "the runner's pipeline key, <branch>.<revision>, a branch escaped as a key's name is (design 47 H §746, H-A-213 (4))"
}, },
"branch": { "branch": {
"type": "string" "type": "string"
@@ -1726,6 +1832,10 @@
"source": { "source": {
"type": "integer" "type": "integer"
}, },
"revision": {
"type": "integer",
"description": "the pipeline's catalog revision number, the number of its key; the indexer frees the pins of that revision, not of another revision of the same source (design 47 H-A-214); absent from an older event"
},
"outcome": { "outcome": {
"type": "string", "type": "string",
"enum": [ "enum": [
@@ -1775,5 +1885,6 @@
"step": "place", "step": "place",
"on": "every" "on": "every"
} }
] ],
"form": 2
} }
@@ -45,6 +45,12 @@
"body": { "body": {
"$ref": "#/defs/StepAsk" "$ref": "#/defs/StepAsk"
} }
},
{
"name": "install",
"body": {
"$ref": "#/defs/StepAsk"
}
} }
], ],
"description": "The Node build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.", "description": "The Node build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.",
+233 -24
View File
@@ -1,11 +1,12 @@
{ {
"format": 1, "format": 1,
"form": 4,
"seat": "node-engine", "seat": "node-engine",
"scope": "node", "scope": "node",
"grain": "whole", "grain": "whole",
"domain": "Core", "domain": "Core",
"decision": "novox/hq ADR 0563", "decision": "novox/hq ADR 0563",
"description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token, or, for an event whose subject names <node>, there (composed.<node>, running.<node>.<module>): the grants part grants a node's account only its own node's subjects (ADR 0363 §2).", "description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 \u00a73, \u00a74): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token, or, for an event whose subject names <node>, there (composed.<node>, running.<node>.<module>): the grants part grants a node's account only its own node's subjects (ADR 0363 \u00a72).",
"acts": [ "acts": [
{ {
"step": "compose", "step": "compose",
@@ -15,7 +16,7 @@
"verbs": [ "verbs": [
{ {
"name": "hand-over", "name": "hand-over",
"description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 §3, §5): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.", "description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 \u00a73, \u00a75): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.",
"input": { "input": {
"properties": { "properties": {
"path": { "path": {
@@ -39,7 +40,7 @@
}, },
{ {
"name": "access-act", "name": "access-act",
"description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 §7, ADR 0563 §3, §4), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 \u00a77, ADR 0563 \u00a73, \u00a74), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.",
"input": { "input": {
"properties": { "properties": {
"access": { "access": {
@@ -68,7 +69,7 @@
}, },
{ {
"name": "judge-directories", "name": "judge-directories",
"description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 §2). Read-only: changes no owner or mode.", "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 \u00a72). Read-only: changes no owner or mode.",
"input": { "input": {
"properties": {}, "properties": {},
"type": "object" "type": "object"
@@ -80,7 +81,7 @@
}, },
{ {
"name": "setuid-search", "name": "setuid-search",
"description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 §2); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 \u00a72); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.",
"input": { "input": {
"properties": { "properties": {
"why": { "why": {
@@ -97,7 +98,7 @@
}, },
{ {
"name": "root-free", "name": "root-free",
"description": "Whether this machine is root-free (novox/hq ADR 0259 §8, ADR 0563 §6): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", "description": "Whether this machine is root-free (novox/hq ADR 0259 \u00a78, ADR 0563 \u00a76): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.",
"input": { "input": {
"properties": {}, "properties": {},
"type": "object" "type": "object"
@@ -121,7 +122,7 @@
}, },
{ {
"name": "acts", "name": "acts",
"description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 §9): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 \u00a79): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.",
"input": { "input": {
"properties": { "properties": {
"id": { "id": {
@@ -242,7 +243,7 @@
"type": "string" "type": "string"
}, },
"digest": { "digest": {
"description": "a composition's digest (sha256:…), to read that revision rather than the latest", "description": "a composition's digest (sha256:\u2026), to read that revision rather than the latest",
"type": "string" "type": "string"
}, },
"module": { "module": {
@@ -287,7 +288,7 @@
}, },
"self": { "self": {
"type": "boolean", "type": "boolean",
"description": "the node composes the module itself (ADR 0547 §2)" "description": "the node composes the module itself (ADR 0547 \u00a72)"
}, },
"backup": { "backup": {
"type": "string", "type": "string",
@@ -455,6 +456,32 @@
}, },
"description": "every resource that differs from what runs, when asked" "description": "every resource that differs from what runs, when asked"
}, },
"drift": {
"type": "array",
"description": "when the diff is asked, each directory entry of what runs that the mesh made, as its record holds, whose owner or mode on disk differ from it (H-A-392 (b), H-A-458 (2)): read-only; the engine sets it right at its next start or apply of the module",
"items": {
"type": "object",
"required": [
"id",
"path",
"drift"
],
"properties": {
"id": {
"type": "string",
"description": "the directory entry's id in the composition"
},
"path": {
"type": "string",
"description": "its path on the machine"
},
"drift": {
"type": "string",
"description": "how its owner or mode on disk differ, in words"
}
}
}
},
"own": { "own": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -517,6 +544,27 @@
"withheld-unknown": { "withheld-unknown": {
"type": "string", "type": "string",
"description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer" "description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer"
},
"withheld-parts": {
"type": "array",
"description": "each part a compose kept because its read did not answer, with why (design 08 control-verbs \u00a74, H-A-321): for the packet filter's holder the part node-packet-filter.allowed, its filter file kept as it runs",
"items": {
"type": "object",
"required": [
"part",
"why"
],
"properties": {
"part": {
"type": "string",
"description": "the read asked, as <seat>.<verb>"
},
"why": {
"type": "string",
"description": "why it did not answer, naming the holder asked"
}
}
}
} }
}, },
"required": [ "required": [
@@ -529,6 +577,63 @@
}, },
"class": "read" "class": "read"
}, },
{
"name": "composition-diff",
"description": "One module's composed values read by resource (design 47 H2 \u00a7813 (3), H-A-349 DQ-12b): given a module and a revision or a digest of its composition, the entries that differ between the composition that runs and that one, per resource, environment entries by name, a secret's value masked. Read-only. Answered by this machine's engine alone.",
"class": "read",
"input": {
"type": "object",
"required": [
"module"
],
"properties": {
"module": {
"type": "string",
"description": "the module, as placed on this machine; node for the node's own"
},
"revision": {
"type": "integer",
"description": "the revision of the module's composition key to compare with, from the revisions the bucket keeps; give it or digest"
},
"digest": {
"type": "string",
"description": "the digest (sha256:\u2026) of the composition to compare with; give it or revision"
}
}
},
"answer": {
"type": "object",
"required": [
"node",
"module",
"resources"
],
"properties": {
"node": {
"type": "string",
"description": "the node"
},
"module": {
"type": "string",
"description": "the module"
},
"running": {
"type": "string",
"description": "the digest of the composition that runs; absent when nothing runs"
},
"other": {
"$ref": "#/defs/Revision"
},
"resources": {
"type": "array",
"description": "each resource with an entry that differs; empty when none differs",
"items": {
"$ref": "#/defs/CompositionDiffResource"
}
}
}
}
},
{ {
"name": "compose", "name": "compose",
"description": "Compose this machine's modules now and say how it went, so a composition that failed, or a module held, recovers without a restart: what the pass refused or held, each with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried again. Changes only what a pass the engine makes on its own would change.", "description": "Compose this machine's modules now and say how it went, so a composition that failed, or a module held, recovers without a restart: what the pass refused or held, each with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried again. Changes only what a pass the engine makes on its own would change.",
@@ -595,7 +700,7 @@
}, },
{ {
"name": "compose-candidate", "name": "compose-candidate",
"description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 §7). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.", "description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 \u00a77). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.",
"optional": true, "optional": true,
"input": { "input": {
"properties": { "properties": {
@@ -640,7 +745,7 @@
"unready", "unready",
"not-judged" "not-judged"
], ],
"description": "the node's verdict (ADR 0593 §7, §9)" "description": "the node's verdict (ADR 0593 \u00a77, \u00a79)"
}, },
"modules": { "modules": {
"type": "array", "type": "array",
@@ -686,7 +791,7 @@
{ {
"name": "manifest-reads", "name": "manifest-reads",
"optional": true, "optional": true,
"description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 §3) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.", "description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 \u00a73) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.",
"input": { "input": {
"type": "object", "type": "object",
"properties": {} "properties": {}
@@ -720,7 +825,7 @@
"node", "node",
"stated-at" "stated-at"
], ],
"description": "what this machine's engine reads of a manifest (ADR 0618 §3)" "description": "what this machine's engine reads of a manifest (ADR 0618 \u00a73)"
}, },
"class": "read" "class": "read"
}, },
@@ -787,7 +892,7 @@
}, },
{ {
"name": "seat-list", "name": "seat-list",
"description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 \u00a77): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.",
"input": { "input": {
"type": "object", "type": "object",
"properties": {} "properties": {}
@@ -798,7 +903,7 @@
}, },
{ {
"name": "seat-list-again", "name": "seat-list-again",
"description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 \u00a77), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.",
"input": { "input": {
"type": "object", "type": "object",
"properties": {} "properties": {}
@@ -1057,6 +1162,52 @@
"$ref": "#/defs/ProcessBuilds" "$ref": "#/defs/ProcessBuilds"
}, },
"class": "read" "class": "read"
},
{
"name": "converged",
"description": "The node's convergence state, which the node-engine keeps (ADR 0168, ADR 0683; design 33 control-verbs \u00a710): adopted or converged, since when it became so, for an adopted node the kind of the firewall found, and the node's links as the engine classifies them: the tunnel's interface and the outward links (design 47 H-A-325). Read-only: the holder of node-packet-filter asks it at its start and at every allow and disallow, and refuses when it does not answer.",
"class": "read",
"input": {
"type": "object",
"properties": {}
},
"answer": {
"type": "object",
"required": [
"state",
"tunnel",
"outward"
],
"properties": {
"state": {
"type": "string",
"enum": [
"adopted",
"converged"
],
"description": "the node's mode: adopted (the found firewall's terms) or converged (the mesh's own filter)"
},
"since": {
"type": "string",
"description": "when the node became so, RFC 3339; absent where the engine recorded no time for it"
},
"found": {
"type": "string",
"description": "the kind of the firewall found, for an adopted node"
},
"tunnel": {
"type": "string",
"description": "the private network's tunnel interface on this node, as the engine's filter render names it"
},
"outward": {
"type": "array",
"items": {
"type": "string"
},
"description": "the links of this node that face outside, as the engine classifies them for its filter render (ADR 0140); an allowance with no interface never opens one"
}
}
}
} }
], ],
"events": [ "events": [
@@ -1205,6 +1356,14 @@
"type": "boolean", "type": "boolean",
"description": "the move changes the build alone" "description": "the move changes the build alone"
}, },
"run": {
"type": "string",
"description": "the composition run's pipeline sequence, in decimal, the module was applied from (design 47 H2 §813 (1), H-A-388): a restarted engine applies no older run again"
},
"pipeline": {
"type": "string",
"description": "the pipeline of the want the module was applied from, its key <branch>.<source>, beside its run (H-A-429 (1), H-A-458 (1)): a want's run is compared with this run only when the want's branch is the same, the key without its last .<source>; absent for a want in none"
},
"kept": { "kept": {
"type": "array", "type": "array",
"items": { "items": {
@@ -1696,7 +1855,7 @@
"description": "one finding of the observer that wrote it" "description": "one finding of the observer that wrote it"
} }
], ],
"description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 §2, ADR 0636 §1); today `machine.<node>.seat-list-unread`" "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 \u00a72, ADR 0636 \u00a71); today `machine.<node>.seat-list-unread`"
}, },
{ {
"name": "bounds", "name": "bounds",
@@ -1708,7 +1867,7 @@
"key": "<what>.<id>", "key": "<what>.<id>",
"value": { "value": {
"type": "object", "type": "object",
"description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G §560, A-77)", "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G \u00a7560, A-77)",
"properties": { "properties": {
"v": { "v": {
"type": "integer", "type": "integer",
@@ -1815,7 +1974,7 @@
}, },
"auto": { "auto": {
"type": "boolean", "type": "boolean",
"description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4)" "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 \u00a74)"
} }
}, },
"required": [ "required": [
@@ -1825,7 +1984,7 @@
"at", "at",
"state" "state"
], ],
"description": "one act asked through the seat, as acts reads it (ADR 0563 §9)" "description": "one act asked through the seat, as acts reads it (ADR 0563 \u00a79)"
}, },
"ActSaid": { "ActSaid": {
"type": "object", "type": "object",
@@ -1870,7 +2029,7 @@
"state", "state",
"node" "node"
], ],
"description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 §1)" "description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 \u00a71)"
}, },
"Acts": { "Acts": {
"type": "object", "type": "object",
@@ -1961,7 +2120,7 @@
"at", "at",
"why" "why"
], ],
"description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 §4)" "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 \u00a74)"
}, },
"Module": { "Module": {
"type": "object", "type": "object",
@@ -2061,7 +2220,7 @@
"why", "why",
"judged" "judged"
], ],
"description": "the engine's root-free verdict (ADR 0563 §6)" "description": "the engine's root-free verdict (ADR 0563 \u00a76)"
}, },
"Said": { "Said": {
"type": "object", "type": "object",
@@ -2106,7 +2265,7 @@
}, },
"SeatList": { "SeatList": {
"type": "object", "type": "object",
"description": "what an engine holds of the seat list (novox/hq ADR 0636 §7)", "description": "what an engine holds of the seat list (novox/hq ADR 0636 \u00a77)",
"properties": { "properties": {
"status": { "status": {
"type": "object", "type": "object",
@@ -2451,6 +2610,10 @@
"type": "string" "type": "string"
} }
}, },
"declaration-reads": {
"type": "integer",
"description": "the declaration Version its engine reads (design 47 H2 §813 (12), H-A-416 (2), H-A-419): the composer writes this node's declaration at the lower of its own Version and this one, 1 when none is stated"
},
"runner-capabilities": { "runner-capabilities": {
"type": "array", "type": "array",
"items": { "items": {
@@ -3160,7 +3323,7 @@
}, },
"Running": { "Running": {
"type": "object", "type": "object",
"description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit", "description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 \u00a72), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit",
"properties": { "properties": {
"v": { "v": {
"type": "integer", "type": "integer",
@@ -3331,6 +3494,52 @@
"step", "step",
"since" "since"
] ]
},
"CompositionDiffEntry": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "the entry: an environment entry by its name, else the part of the resource that differs"
},
"running": {
"type": "string",
"description": "its value in the running composition; absent where the running one lacks it or the value is a secret"
},
"other": {
"type": "string",
"description": "its value in the other composition; absent where the other lacks it or the value is a secret"
},
"masked": {
"type": "boolean",
"description": "the value is a secret, so neither value is given"
}
},
"description": "one entry that differs between the running composition and the other"
},
"CompositionDiffResource": {
"type": "object",
"required": [
"resource",
"entries"
],
"properties": {
"resource": {
"type": "string",
"description": "the resource, as the composition names it"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/CompositionDiffEntry"
},
"description": "the entries of the resource that differ"
}
},
"description": "one resource with the entries of it that differ"
} }
} }
} }
@@ -59,7 +59,7 @@
}, },
{ {
"name": "list", "name": "list",
"description": "Every entry of one directory with its type, owner, group, mode, size and, for a link, its target. At most 2000 entries; a longer directory is cut and says so. A place a secret is kept is refused by name. Read as the node's operator account, through sudo -n where its rights do not reach; a place a secret is kept, or a known credential file, is refused by name.", "description": "Every entry of one directory with its type, owner, group, mode, size and, for a link, its target. At most 2000 entries; a longer directory is cut and says so. A place a secret is kept, at any depth beneath it, is listed too and marked secret-place: its entries, never their content; what reaches a process's memory or files (/proc/<pid>/environ, mem, fd, map_files, root, cwd) is refused by name. Read as the node's operator account, through sudo -n where its rights do not reach.",
"replaces": [ "replaces": [
"ls", "ls",
"ls -la" "ls -la"
@@ -2,13 +2,14 @@
"format": 1, "format": 1,
"seat": "node-packet-filter", "seat": "node-packet-filter",
"scope": "node", "scope": "node",
"grain": "seat-list", "grain": "whole",
"domain": "Connectivity", "domain": "Connectivity",
"decision": "novox/hq ADR 0121", "decision": "novox/hq ADR 0121, ADR 0170, ADR 0683",
"description": "The node seat of the machine's packet filter (ADR 0121, ADR 0170, ADR 0683): what the machine enforces, the mesh's own filter loaded again, one rule set the mesh did not write removed, and the operator's allowances, a port opened by hand beside the ports derived from the modules' listens (design 33 control-verbs). An allowance is the holder's own state, kept one bucket per machine under its node's keys; 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). Each verb is answered on this node's subject; the event allowances-changed is published on mesh.seat.node-packet-filter.event.allowances-changed.<node>.",
"verbs": [ "verbs": [
{ {
"name": "rules", "name": "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.", "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. 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.",
"replaces": [ "replaces": [
"nft list ruleset", "nft list ruleset",
"iptables -L", "iptables -L",
@@ -26,6 +27,42 @@
} }
}, },
"type": "object" "type": "object"
},
"answer": {
"type": "object",
"required": [
"nftables",
"legacy",
"allowances",
"loaded-not-kept"
],
"properties": {
"nftables": {
"type": "string",
"description": "the nftables ruleset, whole or narrowed"
},
"legacy": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "each legacy tool's listing, by tool"
},
"allowances": {
"type": "array",
"items": {
"$ref": "#/defs/Loaded"
},
"description": "allowed's answer, each marked loaded only on a rule comment allowance <key> <at> with an equal at"
},
"loaded-not-kept": {
"type": "array",
"items": {
"$ref": "#/defs/LoadedNotKept"
},
"description": "every allowance comment of the mesh's table whose key is not kept: loaded, not kept"
}
}
} }
}, },
{ {
@@ -37,6 +74,23 @@
"input": { "input": {
"properties": {}, "properties": {},
"type": "object" "type": "object"
},
"answer": {
"type": "object",
"required": [
"loaded",
"table"
],
"properties": {
"loaded": {
"type": "string",
"description": "the filter file loaded"
},
"table": {
"type": "string",
"description": "the mesh's table as loaded"
}
}
} }
}, },
{ {
@@ -57,7 +111,501 @@
"where" "where"
], ],
"type": "object" "type": "object"
},
"answer": {
"type": "object",
"required": [
"where",
"did"
],
"properties": {
"where": {
"type": "string"
},
"did": {
"type": "array",
"items": {
"type": "string"
},
"description": "each command run"
}
}
}
},
{
"name": "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 the holder'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 (for a session's call, the tool runner's account). A key that exists is replaced whole and answered. A kept allowance whose named interface is an outward link, as the node-engine's converged names them, is answered with outward, that link. Written in the hand-act log. Refuses, naming the argument and writing nothing, an unproven caller, an adopted node (naming the adoption) or a node-engine converged that does not answer within 10 s, a bad port, protocol, interface, source or until, an empty or longer why, an unknown argument, a port a derived rule of the loaded mesh table admits from the private network only unless a source is given, and more allowances on the node than the holder's setting allowances-max (default 100). Whether the loaded chain carries it is read with rules.",
"replaces": [
"nft add rule inet mesh input"
],
"class": "act",
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"port",
"why"
],
"properties": {
"port": {
"type": "integer",
"minimum": 1,
"maximum": 65535,
"description": "the port, 1-65535"
},
"protocol": {
"type": "string",
"enum": [
"tcp",
"udp"
],
"description": "tcp (the default) or udp"
},
"interfaces": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z0-9_.-]{1,15}$"
},
"description": "the input interfaces it is opened on, 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)"
},
"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 in the future (optional)"
},
"why": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "why, in words the operator reads (1-500 characters)"
}
}
},
"answer": {
"type": "object",
"required": [
"allowances",
"said"
],
"properties": {
"allowances": {
"type": "array",
"items": {
"$ref": "#/defs/Kept"
}
},
"said": {
"type": "boolean",
"description": "allowances-changed was said with change allowed"
}
}
},
"by-caller": true
},
{
"name": "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. The source is no part of an allowance's identity and is refused as an argument. Written in the hand-act log. Refuses as allow does an unproven caller, an adopted node and a converged that does not answer.",
"replaces": [
"nft delete rule inet mesh input"
],
"class": "act",
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"port",
"why"
],
"properties": {
"port": {
"type": "integer",
"minimum": 1,
"maximum": 65535,
"description": "the port, 1-65535"
},
"protocol": {
"type": "string",
"enum": [
"tcp",
"udp"
],
"description": "tcp (the default) or udp"
},
"interfaces": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z0-9_.-]{1,15}$"
},
"description": "the input interfaces it is opened on, 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)"
},
"why": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "why, in words the operator reads (1-500 characters)"
}
}
},
"answer": {
"type": "object",
"required": [
"allowances",
"said"
],
"properties": {
"allowances": {
"type": "array",
"items": {
"$ref": "#/defs/Allowance"
},
"description": "each allowance as removed"
},
"said": {
"type": "boolean",
"description": "allowances-changed was said with change disallowed"
}
}
},
"by-caller": true
},
{
"name": "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 by the holder, so none answered has expired. The node-engine asks it at every compose of the filter, bound 10 s.",
"class": "read",
"input": {
"type": "object",
"additionalProperties": false,
"properties": {}
},
"answer": {
"type": "object",
"required": [
"allowances"
],
"properties": {
"allowances": {
"type": "array",
"items": {
"$ref": "#/defs/Allowance"
}
}
}
},
"timeout": 10
}
],
"events": [
{
"name": "allowances-changed",
"subject": "allowances-changed.<node>",
"body": {
"$ref": "#/defs/AllowancesChanged"
} }
} }
] ],
"family": {
"name": "node-packet-filter.events",
"max-age-days": 7
},
"states": [
{
"name": "allowances",
"template": "state",
"description": "the operator's allowances, one bucket per machine whose keys carry the node: each holder reads and writes its own node's keys only (design 33 control-verbs §9; design 47 H-A-315 (1), H-A-317)",
"key-forms": [
{
"key": "<node>.allow.<protocol>.<port>",
"value": {
"$ref": "#/defs/AllowanceValue"
},
"description": "the default set: every input interface that is neither the private network's tunnel nor an outward link"
},
{
"key": "<node>.allow.<protocol>.<port>.<interface>",
"value": {
"$ref": "#/defs/AllowanceValue"
},
"description": "one named input interface: every token after the fourth, since a name may hold a dot"
}
],
"history": 1
}
],
"defs": {
"AllowanceValue": {
"type": "object",
"description": "one allowance as the holder keeps it",
"required": [
"port",
"protocol",
"why",
"by",
"at"
],
"properties": {
"port": {
"type": "integer"
},
"protocol": {
"type": "string",
"enum": [
"tcp",
"udp"
]
},
"interface": {
"type": "string",
"description": "the one input interface it is opened on; absent: every input interface that is neither the private network's tunnel nor an outward link"
},
"source": {
"type": "string",
"description": "the IPv4 or IPv6 CIDR it is opened to; absent: any"
},
"until": {
"type": "string",
"description": "when it expires, RFC 3339; absent: never"
},
"why": {
"type": "string"
},
"by": {
"type": "string",
"description": "the caller as the bus named it on the request"
},
"at": {
"type": "string",
"description": "when it was written, RFC 3339, the holder's clock"
}
}
},
"Allowance": {
"type": "object",
"description": "one allowance: a port opened by hand on this machine, with its key",
"required": [
"key",
"port",
"protocol",
"why",
"by",
"at"
],
"properties": {
"key": {
"type": "string",
"description": "its key, allow.<protocol>.<port>[.<interface>]: its key in the holder's state without the node"
},
"port": {
"type": "integer"
},
"protocol": {
"type": "string",
"enum": [
"tcp",
"udp"
]
},
"interface": {
"type": "string",
"description": "the one input interface it is opened on; absent: every input interface that is neither the private network's tunnel nor an outward link"
},
"source": {
"type": "string",
"description": "the IPv4 or IPv6 CIDR it is opened to; absent: any"
},
"until": {
"type": "string",
"description": "when it expires, RFC 3339; absent: never"
},
"why": {
"type": "string"
},
"by": {
"type": "string",
"description": "the caller as the bus named it on the request"
},
"at": {
"type": "string",
"description": "when it was written, RFC 3339, the holder's clock"
}
}
},
"Kept": {
"type": "object",
"description": "one allowance as allow kept it, with what it replaced",
"required": [
"key",
"port",
"protocol",
"why",
"by",
"at"
],
"properties": {
"key": {
"type": "string",
"description": "its key, allow.<protocol>.<port>[.<interface>]: its key in the holder's state without the node"
},
"port": {
"type": "integer"
},
"protocol": {
"type": "string",
"enum": [
"tcp",
"udp"
]
},
"interface": {
"type": "string",
"description": "the one input interface it is opened on; absent: every input interface that is neither the private network's tunnel nor an outward link"
},
"source": {
"type": "string",
"description": "the IPv4 or IPv6 CIDR it is opened to; absent: any"
},
"until": {
"type": "string",
"description": "when it expires, RFC 3339; absent: never"
},
"why": {
"type": "string"
},
"by": {
"type": "string",
"description": "the caller as the bus named it on the request"
},
"at": {
"type": "string",
"description": "when it was written, RFC 3339, the holder's clock"
},
"outward": {
"type": "string",
"description": "the outward link this allowance opens, when its named interface is one of the outward links the node-engine's converged answered for this call; absent: it opens none"
},
"replaced": {
"$ref": "#/defs/Allowance"
}
}
},
"Loaded": {
"type": "object",
"description": "one allowance, marked loaded only when a rule of the mesh's table carries the comment allowance <key> <at> with an equal at",
"required": [
"key",
"port",
"protocol",
"why",
"by",
"at",
"loaded"
],
"properties": {
"key": {
"type": "string",
"description": "its key, allow.<protocol>.<port>[.<interface>]: its key in the holder's state without the node"
},
"port": {
"type": "integer"
},
"protocol": {
"type": "string",
"enum": [
"tcp",
"udp"
]
},
"interface": {
"type": "string",
"description": "the one input interface it is opened on; absent: every input interface that is neither the private network's tunnel nor an outward link"
},
"source": {
"type": "string",
"description": "the IPv4 or IPv6 CIDR it is opened to; absent: any"
},
"until": {
"type": "string",
"description": "when it expires, RFC 3339; absent: never"
},
"why": {
"type": "string"
},
"by": {
"type": "string",
"description": "the caller as the bus named it on the request"
},
"at": {
"type": "string",
"description": "when it was written, RFC 3339, the holder's clock"
},
"loaded": {
"type": "boolean"
}
}
},
"AllowancesChanged": {
"type": "object",
"required": [
"node",
"change",
"allowances",
"at"
],
"properties": {
"node": {
"type": "string"
},
"change": {
"type": "string",
"enum": [
"allowed",
"disallowed",
"expired",
"started"
]
},
"allowances": {
"type": "array",
"items": {
"$ref": "#/defs/Allowance"
},
"description": "the allowances concerned; all of them for started"
},
"by": {
"type": "string",
"description": "who, for allowed and disallowed"
},
"why": {
"type": "string",
"description": "why, for allowed and disallowed"
},
"at": {
"type": "string",
"description": "when it was said, RFC 3339"
}
}
},
"LoadedNotKept": {
"type": "object",
"description": "one allowance comment allowance <key> <at> of the mesh's table whose key is not kept",
"required": [
"key",
"at"
],
"properties": {
"key": {
"type": "string",
"description": "the key the comment names, allow.<protocol>.<port>[.<interface>]"
},
"at": {
"type": "string",
"description": "the at the comment names"
}
}
}
}
} }
@@ -208,6 +208,44 @@
"type": "object" "type": "object"
} }
}, },
{
"name": "kernel-log",
"description": "The kernel's messages (what journalctl -k gives) of this boot or an earlier one, at most 2000 lines, in a time window and narrowed to a priority and to lines holding a text when asked. A secret a line held is shown as [redacted: \u003cwhat it was\u003e].",
"replaces": [
"journalctl -k",
"journalctl -k -b -1",
"dmesg"
],
"input": {
"properties": {
"boot": {
"description": "which boot: 0 this boot (the default), -1 the one before, -2 the one before that, and so on (optional)",
"type": "string"
},
"lines": {
"description": "how many lines from the end of what matches (default 100, at most 2000)",
"type": "string"
},
"match": {
"description": "only the lines holding this text, as written — a fixed string, not a pattern (optional)",
"type": "string"
},
"priority": {
"description": "only entries this severe or more: 0-7 or emerg, alert, crit, err, warning, notice, info, debug (optional)",
"type": "string"
},
"since": {
"description": "the window's start: an RFC 3339 time (2026-10-07T09:30:00Z) or relative to now (-30min, -2h, yesterday) (optional)",
"type": "string"
},
"until": {
"description": "the window's end, in the same forms (optional; now when absent)",
"type": "string"
}
},
"type": "object"
}
},
{ {
"name": "failed", "name": "failed",
"description": "Every failed unit on this machine, in the system manager and in the operator account's; a manager that does not answer is reported with its error, never as nothing failed.", "description": "Every failed unit on this machine, in the system manager and in the operator account's; a manager that does not answer is reported with its error, never as nothing failed.",
@@ -12,7 +12,7 @@
"verbs": [ "verbs": [
{ {
"name": "hold", "name": "hold",
"description": "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 \u00a72); never an image of the holder's own. Emits held.", "description": "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 §2); never an image of the holder's own. Emits held.",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -94,13 +94,21 @@
}, },
{ {
"name": "list", "name": "list",
"description": "What the store holds of one repository, or of every repository the seat holds when none is named: every manifest keeping one bundle or archive, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 \u00a73).", "description": "What the store holds of one repository, or of every repository the seat holds when none is named: every manifest keeping one bundle or archive, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 §3). Filtered by name or module while it reads and paged by the cursor next, at most 768 KB a page, capped saying the rest is read from next (design 47 H2 §779, §811, §813 (7)).",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
"name": { "name": {
"type": "string", "type": "string",
"description": "the repository, <module>/<artifact>; every repository of the seat when not given" "description": "the repository, <module>/<artifact>; every repository of the seat when not given"
},
"module": {
"type": "string",
"description": "only the repositories of this module, <module>/*, applied while reading (design 47 H2 §813 (7))"
},
"next": {
"type": "string",
"description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)"
} }
} }
}, },
@@ -113,6 +121,18 @@
"$ref": "#/defs/Repository" "$ref": "#/defs/Repository"
}, },
"description": "each repository named, in order of its name" "description": "each repository named, in order of its name"
},
"capped": {
"type": "boolean",
"description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811)"
},
"total": {
"type": "integer",
"description": "how many repositories the filters hold in all (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)"
} }
}, },
"required": [ "required": [
@@ -376,5 +396,6 @@
} }
] ]
} }
] ],
"form": 2
} }
+33
View File
@@ -0,0 +1,33 @@
package stdio
import (
"fmt"
"os"
"strings"
"time"
)
// SettingWord is the environment word the node-engine composes a module's config value key into, in a process's
// environment and in the module's slice of the tool runner's MESH_TOOL_ENV alike (design 47 H2 §781; H-A-370):
// MESH_CONFIG_<KEY>, the key upper-cased with '-' and '.' written '_', holding the value as text.
func SettingWord(key string) string {
return "MESH_CONFIG_" + strings.ToUpper(strings.NewReplacer("-", "_", ".", "_").Replace(key))
}
// Setting is the module's config value key as the node-engine composed it, and whether it composed one: the one
// settings reader of a process and a bundle (§781).
func Setting(key string) (string, bool) { return os.LookupEnv(SettingWord(key)) }
// SettingDuration is the config value key read as a Go duration ("10m"): def when none is composed or it is empty, an
// error naming the key for a value that is no duration above zero.
func SettingDuration(key string, def time.Duration) (time.Duration, error) {
v, ok := Setting(key)
if v = strings.TrimSpace(v); !ok || v == "" {
return def, nil
}
d, err := time.ParseDuration(v)
if err != nil || d <= 0 {
return 0, fmt.Errorf("the setting %s (%s) holds %q, which is not a duration above zero", key, SettingWord(key), v)
}
return d, nil
}
+6
View File
@@ -0,0 +1,6 @@
package stdio
// SetupStarved opens the one line a test prints when its setup wait on the bus passed the setup bound (design 47 H2
// §800, H-A-368): a build module reads it in the test output, never an assertion's words, and runs the level again. It
// lives in the root package so the delivery SDK reads it without importing the test helpers (H-A-399).
const SetupStarved = "mesh: setup starved:"
+51 -11
View File
@@ -22,6 +22,13 @@ type StateEntry struct {
Value json.RawMessage `json:"value"` Value json.RawMessage `json:"value"`
Revision uint64 `json:"revision"` Revision uint64 `json:"revision"`
At time.Time `json:"at,omitzero"` At time.Time `json:"at,omitzero"`
// SeenAgain is set in a page (Page) on a key written again since an earlier page of the same read handed it over,
// so a reader knows this value replaces the one it holds (design 47 H2 §779). Get never sets it.
SeenAgain bool `json:"seen-again,omitempty"`
// Deleted is set in a page (Page) on a key's delete marker, at its sequence, with no value: a reader following pages
// removes the key, so a deleted key never comes back alive from a bucket with history (design 47 H2 §779, H-A-451
// (1)). Get never sets it.
Deleted bool `json:"deleted,omitempty"`
} }
// The operations a watch hands over (StateChange.Op). // The operations a watch hands over (StateChange.Op).
@@ -107,18 +114,35 @@ func (s KeptState) Get(key string) (*StateEntry, error) {
return &e, json.Unmarshal(raw, &e) return &e, json.Unmarshal(raw, &e)
} }
// StatePage is the values of one bulk read: those after a key, in key order, and the key to ask after for the rest. // StatePage is the values of one page of a read: those the bus wrote after the cursor's sequence, in sequence order,
// and the cursor to hand back for the rest (design 47 H2 §779).
type StatePage struct { type StatePage struct {
Entries []StateEntry `json:"entries"` Entries []StateEntry `json:"entries"`
// Next is the last key of Entries when more follow it, else empty. // Next is the opaque cursor that continues the read, empty at its end.
Next string `json:"next,omitempty"` Next string `json:"next,omitempty"`
} }
// Page is the current values in key order after the key `after`, as many as fit maxBytes (keys and values) or the time budget allows, at least // Page is one page of the state's values, in the order the bus wrote them, after the opaque cursor (empty: from the
// one: one request for many values, where Get is one request each. A runtime that does not answer it gives an error // start), as many as fit maxBytes (keys and values; the runtime holds a page to 768 KB at most) or the time budget
// satisfying errors.Is(err, errors.ErrUnsupported), and the reader asks Get per key instead. // allows, at least one: runtime verb `mesh/state.page`, read from an ordered consumer after the cursor's sequence, so a
func (s KeptState) Page(after string, maxBytes int, budget time.Duration) (StatePage, error) { // state is read once however many pages it takes (design 47 H2 §779). A key written again between two pages comes
raw, err := s.ask("page", map[string]any{"after": after, "max_bytes": maxBytes, "budget_ms": budget.Milliseconds()}) // again in a later page with SeenAgain set, and a key deleted comes as an entry with Deleted set and no value. A keep (KeepPrefix) is not an entry and is left out. Hand Next back for the next page. A runtime that does not answer it gives an
// error satisfying errors.Is(err, errors.ErrUnsupported), and the reader asks Get per key instead.
func (s KeptState) Page(cursor string, maxBytes int, budget time.Duration) (StatePage, error) {
p, err := s.page(cursor, maxBytes, budget)
kept := p.Entries[:0]
for _, e := range p.Entries {
if !IsKeep(e.Key) {
kept = append(kept, e)
}
}
p.Entries = kept
return p, err
}
// page is one page as the runtime answers it, keeps included (KeepPrefix).
func (s KeptState) page(cursor string, maxBytes int, budget time.Duration) (StatePage, error) {
raw, err := s.ask("page", map[string]any{"cursor": cursor, "max_bytes": maxBytes, "budget_ms": budget.Milliseconds()})
if err != nil { if err != nil {
return StatePage{}, err return StatePage{}, err
} }
@@ -257,14 +281,23 @@ func (s KeptState) Increment(key string, attempts int) (uint64, error) {
return 0, fmt.Errorf("%s was written by another writer first %d times: %w", key, attempts, ErrChanged) return 0, fmt.Errorf("%s was written by another writer first %d times: %w", key, attempts, ErrChanged)
} }
// Keys is every key with a current value, sorted. // Keys is every key with a current value, sorted; a keep (KeepPrefix) is not an entry and is left out.
func (s KeptState) Keys() ([]string, error) { func (s KeptState) Keys() ([]string, error) {
raw, err := s.ask("keys", map[string]any{}) raw, err := s.ask("keys", map[string]any{})
if err != nil { if err != nil {
return nil, err return nil, err
} }
var keys []string var all []string
return keys, json.Unmarshal(raw, &keys) if err := json.Unmarshal(raw, &all); err != nil {
return nil, err
}
keys := all[:0]
for _, k := range all {
if !IsKeep(k) {
keys = append(keys, k)
}
}
return keys, nil
} }
// Watch hands handle every current value — none that is deleted — and then every change, in order, // Watch hands handle every current value — none that is deleted — and then every change, in order,
@@ -279,7 +312,14 @@ func (s KeptState) Watch(key string, handle func(StateChange) error) error {
return err return err
} }
id := c.newID() id := c.newID()
f := newFollower("the watch "+id+" of the state "+s.name, handle, func(ch StateChange) string { return ch.Op + " " + ch.Key }) // A keep (KeepPrefix) is not an entry of the state: no watcher hears it.
entries := func(ch StateChange) error {
if IsKeep(ch.Key) {
return nil
}
return handle(ch)
}
f := newFollower("the watch "+id+" of the state "+s.name, entries, func(ch StateChange) string { return ch.Op + " " + ch.Key })
c.mu.Lock() c.mu.Lock()
c.watches[id] = f c.watches[id] = f
c.mu.Unlock() c.mu.Unlock()
+24 -3
View File
@@ -38,7 +38,7 @@ func historying(t *testing.T, answer func(message) map[string]any, run func()) [
if json.Unmarshal(lines.Bytes(), &m) != nil { if json.Unmarshal(lines.Bytes(), &m) != nil {
continue continue
} }
if strings.HasPrefix(m.Method, "mesh/state.") { if strings.HasPrefix(m.Method, "mesh/state.") || strings.HasPrefix(m.Method, "mesh/queue.") {
amu.Lock() amu.Lock()
asked = append(asked, m) asked = append(asked, m)
amu.Unlock() amu.Unlock()
@@ -143,13 +143,23 @@ func TestHistoryIsEveryKeptValueOldestFirst(t *testing.T) {
} }
// Info asks mesh/state.info with the state alone and hands back the bucket's fill against its caps, as the tool // Info asks mesh/state.info with the state alone and hands back the bucket's fill against its caps, as the tool
// runner answers it (design 47 G §623); a refusal is the runtime's error. // runner answers it (design 47 G §623); a refusal is the runtime's error. QueueWaiting asks mesh/queue.waiting with the
// seat alone and hands back its waiting asks and whether they were cut (design 47 H2 §777, H-A-410).
func TestInfoIsTheBucketsFillAgainstItsCaps(t *testing.T) { func TestInfoIsTheBucketsFillAgainstItsCaps(t *testing.T) {
var got *StateInfo var got *StateInfo
var refused error var refused error
var waiting Waiting
var waitingRefused error
asked := historying(t, func(m message) map[string]any { asked := historying(t, func(m message) map[string]any {
var p map[string]any var p map[string]any
_ = json.Unmarshal(m.Params, &p) _ = json.Unmarshal(m.Params, &p)
if m.Method == "mesh/queue.waiting" {
if p["seat"] != "mesh-wants" || len(p) != 1 {
return map[string]any{"error": map[string]any{"code": -32000, "message": "issued no queue of that seat"}}
}
return map[string]any{"result": map[string]any{"asks": []map[string]any{{"id": "main.9", "module": "mesh-delivery-pipeline",
"age_seconds": 42}, {"id": "main.10", "module": "mesh-delivery-pipeline", "age_seconds": 1.5, "again": true}}, "capped": true}}
}
if p["state"] != "issues" { if p["state"] != "issues" {
return map[string]any{"error": map[string]any{"code": -32000, "message": "issues was issued no state"}} return map[string]any{"error": map[string]any{"code": -32000, "message": "issues was issued no state"}}
} }
@@ -164,8 +174,19 @@ func TestInfoIsTheBucketsFillAgainstItsCaps(t *testing.T) {
if i, refused = State("elsewhere.issues").Info(); i != nil { if i, refused = State("elsewhere.issues").Info(); i != nil {
t.Errorf("a refused info handed back %v", i) t.Errorf("a refused info handed back %v", i)
} }
if waiting, err = QueueWaiting("mesh-wants"); err != nil {
t.Errorf("waiting: %v", err)
}
_, waitingRefused = QueueWaiting("node-build-go")
}) })
if len(asked) != 2 || asked[0].Method != "mesh/state.info" { if w := waiting; !w.Capped || len(w.Asks) != 2 || w.Asks[0] != (WaitingAsk{ID: "main.9", Module: "mesh-delivery-pipeline", AgeSeconds: 42}) ||
w.Asks[1] != (WaitingAsk{ID: "main.10", Module: "mesh-delivery-pipeline", AgeSeconds: 1.5, Again: true}) {
t.Errorf("the waiting asks are %+v", w)
}
if waitingRefused == nil || !strings.Contains(waitingRefused.Error(), "issued no queue") {
t.Errorf("a refused waiting read answered %v", waitingRefused)
}
if len(asked) != 4 || asked[0].Method != "mesh/state.info" || asked[2].Method != "mesh/queue.waiting" {
t.Fatalf("asked %+v", asked) t.Fatalf("asked %+v", asked)
} }
if got == nil || got.Bytes != 300 || got.MaxBytes != 1000 || got.Keys != 4 || got.Bucket != "issues_issues" || !got.KeyTTL { if got == nil || got.Bytes != 300 || got.MaxBytes != 1000 || got.Keys != 4 || got.Bucket != "issues_issues" || !got.KeyTTL {
+302
View File
@@ -6,7 +6,9 @@ import (
"errors" "errors"
"fmt" "fmt"
"io" "io"
"sort"
"strings" "strings"
"sync"
"testing" "testing"
"time" "time"
) )
@@ -56,6 +58,12 @@ func TestABundleKeepsAndWatchesStateThroughTheRuntime(t *testing.T) {
} }
return State("servers").PutTTL(a["key"].(string), 1, 90*time.Second) return State("servers").PutTTL(a["key"].(string), 1, 90*time.Second)
}}, }},
{Name: "take", Run: func(a map[string]any) (any, error) {
return State("servers").TakeOnce(a["seat"].(string), a["ask"].(string), 10*time.Minute)
}},
{Name: "page", Run: func(a map[string]any) (any, error) {
return State("servers").Page(a["cursor"].(string), 1000, time.Second)
}},
}, inR, outW) }, inR, outW)
}() }()
lines := bufio.NewScanner(outR) lines := bufio.NewScanner(outR)
@@ -219,6 +227,48 @@ func TestABundleKeepsAndWatchesStateThroughTheRuntime(t *testing.T) {
t.Fatalf("the put answered %v", r) t.Fatalf("the put answered %v", r)
} }
} }
// Design 47 H2 §775, H-A-359: a bundle takes an ask once: the create of <seat>.<ask> with the ask's bound as its time
// to live answers true, the runtime's refusal as changed answers false, and an ask with no id is refused unasked.
for i, exists := range []bool{false, true} {
send(map[string]any{"jsonrpc": "2.0", "id": 40 + i, "method": "tools/call", "params": map[string]any{"name": "take",
"arguments": map[string]any{"seat": "git", "ask": "a-7"}}})
asked := next()
p := asked["params"].(map[string]any)
if asked["method"] != "mesh/state.create" || p["key"] != "git.a-7" || p["ttl_seconds"] != float64(600) {
t.Fatalf("asked %v", asked)
}
if exists {
send(map[string]any{"jsonrpc": "2.0", "id": asked["id"], "error": map[string]any{"code": CodeChanged, "message": "exists"}})
} else {
send(map[string]any{"jsonrpc": "2.0", "id": asked["id"], "result": map[string]any{"revision": 5}})
}
r := next()
if text := fmt.Sprint(r["result"]); r["id"] != float64(40+i) || !strings.Contains(text, map[bool]string{false: "true", true: "false"}[exists]) {
t.Fatalf("a take, the key existing %v, answered %v", exists, r)
}
}
send(map[string]any{"jsonrpc": "2.0", "id": 42, "method": "tools/call", "params": map[string]any{"name": "take",
"arguments": map[string]any{"seat": "git", "ask": ""}}})
if r := next(); r["id"] != float64(42) || !strings.Contains(fmt.Sprint(r), "is not an ask id") {
t.Fatalf("a take with no ask id answered %v", r)
}
// Design 47 H2 §779: a page read hands the runtime the opaque cursor and answers the cursor that continues it, and a
// key written again since an earlier page comes marked seen-again; a kept delete comes as an entry marked deleted with
// no value (H-A-451 (1)).
send(map[string]any{"jsonrpc": "2.0", "id": 43, "method": "tools/call", "params": map[string]any{"name": "page",
"arguments": map[string]any{"cursor": "c.17"}}})
if asked := next(); asked["method"] != "mesh/state.page" || asked["params"].(map[string]any)["cursor"] != "c.17" || asked["params"].(map[string]any)["after"] != nil {
t.Fatalf("asked %v", asked)
} else {
send(map[string]any{"jsonrpc": "2.0", "id": asked["id"], "result": map[string]any{"next": "c.19", "entries": []any{
map[string]any{"key": "a", "value": 1, "revision": 18}, map[string]any{"key": "b", "value": 2, "revision": 19, "seen-again": true},
map[string]any{"key": "c", "revision": 20, "deleted": true}}}})
}
if r := next(); r["id"] != float64(43) || !strings.Contains(fmt.Sprint(r), `"next":"c.19"`) || !strings.Contains(fmt.Sprint(r), `"revision":19,"seen-again":true`) ||
strings.Count(fmt.Sprint(r), "seen-again") != 1 || !strings.Contains(fmt.Sprint(r), `"key":"c","value":null,"revision":20,"deleted":true`) ||
strings.Count(fmt.Sprint(r), "deleted") != 1 {
t.Fatalf("the page answered %v", r)
}
if !errors.Is(&refused{code: CodeChanged, message: "x"}, ErrChanged) { if !errors.Is(&refused{code: CodeChanged, message: "x"}, ErrChanged) {
t.Fatal("a refusal coded -32010 is not ErrChanged") t.Fatal("a refusal coded -32010 is not ErrChanged")
} }
@@ -307,4 +357,256 @@ func TestABundleKeepsAndWatchesStateThroughTheRuntime(t *testing.T) {
if v, _, _ := w.Get("placement", "gone"); string(v) != "again" { if v, _, _ := w.Get("placement", "gone"); string(v) != "again" {
t.Fatalf("a change after its own delete is not taken: %s", v) t.Fatalf("a change after its own delete is not taken: %s", v)
} }
// Design 47 H2 §782: one bundle's state calls through its one runtime channel are safe at once: gets, puts, pages,
// watches and bus-state calls from many goroutines, the runtime answering each, under the race detector.
t.Run("one runtime channel serves concurrent state calls", func(t *testing.T) {
inR, inW := io.Pipe()
outR, outW := io.Pipe()
t.Cleanup(func() { _ = inW.Close(); _ = outR.Close() })
const many = 16
go func() {
_ = ServeOn("", []Tool{{Name: "many", Run: func(map[string]any) (any, error) {
var wg sync.WaitGroup
errs := make(chan error, many*6)
for i := range many {
wg.Add(1)
go func() {
defer wg.Done()
s, key := State("servers"), fmt.Sprintf("k%d", i)
_, err := s.Put(key, i)
errs <- err
_, err = s.Get(key)
errs <- err
_, err = s.Page("", 1000, time.Second)
errs <- err
errs <- s.Watch(key, func(StateChange) error { return nil })
_, err = BusState("mesh/objects.info", map[string]any{"objects": "o"})
errs <- err
_, err = s.Info()
errs <- err
}()
}
wg.Wait()
close(errs)
for err := range errs {
if err != nil {
return nil, err
}
}
return "done", nil
}}}, inR, outW)
}()
var wmu sync.Mutex
send := func(m map[string]any) {
b, _ := json.Marshal(m)
wmu.Lock()
defer wmu.Unlock()
_, _ = inW.Write(append(b, '\n'))
}
send(map[string]any{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": map[string]any{"name": "many"}})
lines := bufio.NewScanner(outR)
answered := make(chan map[string]any, 1)
go func() {
n := 1000
for lines.Scan() {
var m map[string]any
_ = json.Unmarshal(lines.Bytes(), &m)
method, _ := m["method"].(string)
switch {
case m["id"] == float64(1):
answered <- m
return
case method == "mesh/state.watch":
n++
id := m["id"]
key := m["params"].(map[string]any)["key"]
// The runtime hands the current value over, then answers the watch, on a goroutine of its own, as
// the tool runner's answers come in any order.
go func(n int) {
send(map[string]any{"jsonrpc": "2.0", "id": n, "method": "mesh/state", "params": map[string]any{"watch": id,
"change": map[string]any{"state": "servers", "key": key, "op": "put", "value": 1, "current": true}}})
send(map[string]any{"jsonrpc": "2.0", "id": id, "result": map[string]any{}})
}(n)
case method == "mesh/state.page":
go send(map[string]any{"jsonrpc": "2.0", "id": m["id"], "result": map[string]any{"entries": []any{}}})
case method == "mesh/state.get":
go send(map[string]any{"jsonrpc": "2.0", "id": m["id"], "result": map[string]any{"key": "k", "value": 1, "revision": 2}})
case method != "":
go send(map[string]any{"jsonrpc": "2.0", "id": m["id"], "result": map[string]any{"revision": 1}})
}
}
}()
select {
case m := <-answered:
if m["error"] != nil || fmt.Sprint(m["result"]) != "map[content:[map[text:\"done\" type:text]]]" {
t.Fatalf("the concurrent calls answered %v", m)
}
case <-time.After(10 * time.Second):
t.Fatal("the concurrent calls did not end")
}
})
// Design 47 H2 §812 (H-A-380, H-A-386): prune-mark and prune-target are read through the settings reader with their
// defaults, and a bundle's Put judges the fill the runtime's put answer carries: past 70 % the oldest keys by revision
// are deleted to 50 %, a key kept under _keep/<key> survives, and no reader (Keys, Page) counts the keep.
t.Run("a write past its mark prunes to its target and a kept key survives", func(t *testing.T) {
t.Run("settings", func(t *testing.T) {
if p, err := PruneSettings(); err != nil || p != (Prune{Mark: 70, Target: 50}) {
t.Fatalf("the defaults are %+v, %v", p, err)
}
t.Setenv(SettingWord(PruneMarkSetting), "80%")
t.Setenv(SettingWord(PruneTargetSetting), "60")
if p, err := PruneSettings(); err != nil || p != (Prune{Mark: 80, Target: 60}) {
t.Fatalf("the settings read %+v, %v", p, err)
}
t.Setenv(SettingWord(PruneTargetSetting), "90")
if _, err := PruneSettings(); err == nil || !strings.Contains(err.Error(), "prune-target") {
t.Fatalf("a target above the mark was taken: %v", err)
}
t.Setenv(SettingWord(PruneTargetSetting), "half")
if _, err := PruneSettings(); err == nil || !strings.Contains(err.Error(), "MESH_CONFIG_PRUNE_TARGET") {
t.Fatalf("a target that is no percentage was taken: %v", err)
}
})
servesAlone(t)
t.Setenv(ServedAs, "bridge")
inR, inW := io.Pipe()
outR, outW := io.Pipe()
pruned := State("performed").Pruned(Prune{Mark: 70, Target: 50})
go func() {
_ = ServeOn("", []Tool{
{Name: "write", Run: func(a map[string]any) (any, error) { return pruned.Put(a["key"].(string), a["value"]) }},
{Name: "keep", Run: func(a map[string]any) (any, error) {
return nil, pruned.Keep(a["key"].(string), time.Now().Add(time.Hour))
}},
{Name: "keys", Run: func(map[string]any) (any, error) { return State("performed").Keys() }},
{Name: "page", Run: func(map[string]any) (any, error) { return State("performed").Page("", 1<<20, time.Second) }},
}, inR, outW)
}()
// The runtime: a state of a cap of 10000 bytes whose fill is what its current values put.
const limit = 10_000
var mu sync.Mutex
values, revs, next := map[string]json.RawMessage{}, map[string]uint64{}, uint64(0)
held := func() uint64 {
var n uint64
for k, v := range values {
n += PutBytes(k, v)
}
return n
}
var mostHeld uint64
answers := make(chan map[string]any, 1)
send := func(m map[string]any) { b, _ := json.Marshal(m); _, _ = inW.Write(append(b, '\n')) }
go func() {
lines := bufio.NewScanner(outR)
lines.Buffer(make([]byte, 1<<20), 1<<22)
for lines.Scan() {
var m struct {
ID any `json:"id"`
Method string `json:"method"`
Params map[string]any `json:"params"`
Result any `json:"result"`
Error any `json:"error"`
}
_ = json.Unmarshal(lines.Bytes(), &m)
if m.Method == "" {
answers <- map[string]any{"result": m.Result, "error": m.Error}
continue
}
mu.Lock()
var result any = map[string]any{}
key, _ := m.Params["key"].(string)
switch m.Method {
case "mesh/state.put":
v, _ := json.Marshal(m.Params["value"])
next++
values[key], revs[key] = v, next
mostHeld = max(mostHeld, held())
result = map[string]any{"revision": next, "fill": map[string]any{"count": len(values), "bytes": held(), "max_bytes": limit}}
case "mesh/state.delete":
delete(values, key)
case "mesh/state.keys":
keys := []string{}
for k := range values {
keys = append(keys, k)
}
sort.Strings(keys)
result = keys
case "mesh/state.page":
var entries []StateEntry
for k, v := range values {
entries = append(entries, StateEntry{Key: k, Value: v, Revision: revs[k]})
}
sort.Slice(entries, func(i, j int) bool { return entries[i].Revision < entries[j].Revision })
result = StatePage{Entries: entries}
}
mu.Unlock()
if m.ID != nil {
send(map[string]any{"jsonrpc": "2.0", "id": m.ID, "result": result})
}
}
}()
call := func(name string, args map[string]any) any {
t.Helper()
send(map[string]any{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": map[string]any{"name": name, "arguments": args}})
select {
case a := <-answers:
r, _ := a["result"].(map[string]any)
if a["error"] != nil || r == nil || r["isError"] == true {
t.Fatalf("%s answered %v %v", name, a["error"], r)
}
var out any
_ = json.Unmarshal([]byte(r["content"].([]any)[0].(map[string]any)["text"].(string)), &out)
return out
case <-time.After(3 * time.Second):
t.Fatalf("%s answered nothing", name)
return nil
}
}
value := strings.Repeat("x", 300)
call("write", map[string]any{"key": "k00", "value": value})
call("keep", map[string]any{"key": "k00"})
for _, k := range []string{"k01", "k02", "k03", "k04", "k05", "k06", "k07", "k08", "k09", "k10", "k11", "k12", "k13", "k14", "k15", "k16", "k17", "k18", "k19"} {
call("write", map[string]any{"key": k, "value": value})
mu.Lock()
over := held()*100 > 70*limit
mu.Unlock()
if over {
t.Fatalf("the state holds more than 70 %% of its cap after %s: no prune", k)
}
}
mu.Lock()
_, k00 := values["k00"]
_, k01 := values["k01"]
_, k19 := values["k19"]
_, keep := values[KeepKey("k00")]
after := held()
mu.Unlock()
if mostHeld*100 <= 70*limit {
t.Fatalf("the test never took the state past its mark (%d bytes at most)", mostHeld)
}
if !k00 || !keep || k01 || !k19 {
t.Fatalf("after the prunes k00 %v, its keep %v, k01 %v, k19 %v: want the kept key and its keep, the oldest other gone, the newest there", k00, keep, k01, k19)
}
if after*100 > 70*limit {
t.Fatalf("the state holds %d of %d bytes", after, limit)
}
if keys := call("keys", nil); strings.Contains(strings.Join(strs(keys), " "), KeepPrefix) {
t.Fatalf("Keys counted the keep: %v", keys)
}
page := call("page", nil).(map[string]any)
for _, e := range page["entries"].([]any) {
if IsKeep(e.(map[string]any)["key"].(string)) {
t.Fatalf("Page counted the keep: %v", e)
}
}
})
}
func strs(v any) []string {
var out []string
for _, s := range v.([]any) {
out = append(out, s.(string))
}
return out
} }
+109
View File
@@ -0,0 +1,109 @@
package stateobjects
import (
"errors"
"fmt"
"strings"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/views"
)
// Pruning is one state a module prunes toward its cap (design 47 H2 §812): its local name in the manifest, and the
// pruned state (a process's process.PrunedState or a bundle's stdio.PrunedState).
type Pruning struct {
Name string
State stdio.Prunable
}
// PruneTools are the two generic tools of a module that prunes its states (design 47 H2 §812; H-A-380 (3)), named for
// the module as Tools names its own: `<module>_state_prune_now` (entry, why) prunes an entry to its target now, and
// `<module>_state_keep` (entry, key, until, why) keeps a key from the prune until a time. Each is written in the hand-act
// log before anything is done, and refused when it cannot be.
func PruneTools(module string, entries []Pruning, acts views.HandActs) []stdio.Tool {
if len(entries) == 0 {
return nil
}
var names []string
for _, e := range entries {
names = append(names, e.Name)
}
entryArg := map[string]any{"type": "string", "description": "the state pruned: its local name in the manifest, one of " + strings.Join(names, ", ")}
whyArg := map[string]any{"type": "string", "description": "why, in plain words"}
pick := func(args map[string]any) (Pruning, string, error) {
why, _ := args["why"].(string)
if why = strings.TrimSpace(why); why == "" {
return Pruning{}, "", errors.New("a prune or a keep names why: nothing was done")
}
name, _ := args["entry"].(string)
name = strings.TrimSpace(name)
for _, e := range entries {
if e.Name == name || (name == "" && len(entries) == 1) {
return e, why, nil
}
}
return Pruning{}, "", fmt.Errorf("entry names one of %s, not %q: nothing was done", strings.Join(names, ", "), name)
}
recorded := func(tool, what, why, cause string) error {
if acts == nil {
return errors.New("no way to record a hand act is given, so nothing was done")
}
if err := acts.RecordHandAct(views.HandAct{What: what, Why: why, Cause: cause, Verb: tool}); err != nil {
return fmt.Errorf("the hand act was not recorded, so nothing was done: %w", err)
}
return nil
}
pruneNow, keep := module+"_state_prune_now", module+"_state_keep"
return []stdio.Tool{
{
Name: pruneNow,
Description: "Prune one of " + module + "'s states to its prune-target now, oldest keys first, whatever its fill (design 47 §812). " +
"A key kept by " + keep + " stays. Written in the hand-act log first; needs why. Answers the keys removed and the fill before and after.",
Input: map[string]any{"type": "object", "required": []string{"why"}, "properties": map[string]any{"entry": entryArg, "why": whyArg}},
Run: func(args map[string]any) (any, error) {
e, why, err := pick(args)
if err != nil {
return nil, err
}
if err := recorded(pruneNow, "pruned "+module+"'s state "+e.Name+" to its target now", why, "state-pruned"); err != nil {
return nil, err
}
return e.State.PruneNow()
},
},
{
Name: keep,
Description: "Keep one key of one of " + module + "'s states from the prune until a time (design 47 §812): the keep is kept in the state " +
"itself under " + stdio.KeepPrefix + "<key>, never pruned and never counted as an entry. Written in the hand-act log first; needs key, until and why.",
Input: map[string]any{"type": "object", "required": []string{"key", "until", "why"}, "properties": map[string]any{
"entry": entryArg,
"key": map[string]any{"type": "string", "description": "the key kept"},
"until": map[string]any{"type": "string", "description": "until when, an RFC 3339 time still to come"},
"why": whyArg,
}},
Run: func(args map[string]any) (any, error) {
e, why, err := pick(args)
if err != nil {
return nil, err
}
key, _ := args["key"].(string)
text, _ := args["until"].(string)
until, err := time.Parse(time.RFC3339, strings.TrimSpace(text))
if err != nil {
return nil, fmt.Errorf("until %q is not an RFC 3339 time: nothing was kept", text)
}
if err := stdio.KeepProblem(key, until); err != nil {
return nil, fmt.Errorf("%w: nothing was kept", err)
}
if err := recorded(keep, "kept the key "+key+" of "+module+"'s state "+e.Name+" from the prune until "+until.UTC().Format(time.RFC3339), why, "state-kept"); err != nil {
return nil, err
}
if err := e.State.Keep(key, until); err != nil {
return nil, err
}
return map[string]any{"entry": e.Name, "key": key, "kept-as": stdio.KeepKey(key), "until": until.UTC()}, nil
},
},
}
}
+59
View File
@@ -0,0 +1,59 @@
package stateobjects
import (
"errors"
"strings"
"testing"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
)
type prunable struct {
pruned int
kept map[string]time.Time
}
func (p *prunable) PruneNow() (stdio.Pruned, error) {
p.pruned++
return stdio.Pruned{State: "performed"}, nil
}
func (p *prunable) Keep(key string, until time.Time) error {
p.kept[key] = until
return nil
}
// Design 47 H2 §812 (H-A-380 (3)): `<module>_state_prune_now` (entry, why) and `<module>_state_keep` (entry, key, until,
// why) are written in the hand-act log before they act, and do nothing without why or when the act is not recorded.
func subThePruneToolsPruneAndKeepAsHandActs(t *testing.T) {
p := &prunable{kept: map[string]time.Time{}}
a := &acts{}
tools := map[string]stdio.Tool{}
for _, tool := range PruneTools("mesh-forge-bridge", []Pruning{{Name: "performed", State: p}}, a) {
tools[tool.Name] = tool
}
now, keep := tools["mesh-forge-bridge_state_prune_now"], tools["mesh-forge-bridge_state_keep"]
if now.Run == nil || keep.Run == nil {
t.Fatalf("the tools are %v", tools)
}
if _, err := now.Run(map[string]any{"entry": "performed"}); err == nil || p.pruned != 0 {
t.Fatalf("a prune without why ran: %v", err)
}
if _, err := now.Run(map[string]any{"entry": "performed", "why": "full before a delivery"}); err != nil || p.pruned != 1 {
t.Fatalf("prune now: %v, pruned %d", err, p.pruned)
}
until := time.Now().Add(24 * time.Hour).UTC().Format(time.RFC3339)
if _, err := keep.Run(map[string]any{"entry": "performed", "key": "pr.42", "until": until, "why": "the proof reads it"}); err != nil || p.kept["pr.42"].IsZero() {
t.Fatalf("keep: %v, kept %v", err, p.kept)
}
if _, err := keep.Run(map[string]any{"key": "pr.43", "until": "2000-01-01T00:00:00Z", "why": "late"}); err == nil || !p.kept["pr.43"].IsZero() {
t.Fatalf("a keep until a time past was taken: %v", err)
}
if len(a.done) != 2 || a.done[0].Verb != "mesh-forge-bridge_state_prune_now" || !strings.Contains(a.done[1].What, "pr.42") || a.done[1].Why != "the proof reads it" {
t.Fatalf("the hand acts are %+v", a.done)
}
a.err = errors.New("the hand-act log refused")
if _, err := now.Run(map[string]any{"why": "again"}); err == nil || p.pruned != 1 {
t.Fatalf("a prune not recorded ran: %v", err)
}
}
+1
View File
@@ -40,4 +40,5 @@ func TestABodyIsAReferenceOnlyWhenItIsExactlyOne(t *testing.T) {
t.Run("ValuesOfAnySizeThroughTheRuntime", subValuesOfAnySizeThroughTheRuntime) t.Run("ValuesOfAnySizeThroughTheRuntime", subValuesOfAnySizeThroughTheRuntime)
t.Run("AWriteLostLeavesNoObjectBehind", subAWriteLostLeavesNoObjectBehind) t.Run("AWriteLostLeavesNoObjectBehind", subAWriteLostLeavesNoObjectBehind)
t.Run("AValueLargerThanTheStoreTakesIsRefused", subAValueLargerThanTheStoreTakesIsRefused) t.Run("AValueLargerThanTheStoreTakesIsRefused", subAValueLargerThanTheStoreTakesIsRefused)
t.Run("ThePruneToolsPruneAndKeepAsHandActs", subThePruneToolsPruneAndKeepAsHandActs)
} }
+7 -3
View File
@@ -26,6 +26,7 @@ import (
"sync" "sync"
"time" "time"
"git.novox.be/novox/mesh-sdk/go/busretry"
"git.novox.be/novox/mesh-sdk/go/calladdress" "git.novox.be/novox/mesh-sdk/go/calladdress"
) )
@@ -191,6 +192,9 @@ func ServeOn(name string, tools []Tool, in io.Reader, out io.Writer) error {
if name == "" { if name == "" {
name = "bundle" name = "bundle"
} }
if err := busretry.ReadPace(SettingDuration); err != nil {
return fmt.Errorf("the kept-call pace of %s: %w", name, err)
}
byName := map[string]Tool{} byName := map[string]Tool{}
for _, t := range tools { for _, t := range tools {
byName[t.Name] = t byName[t.Name] = t
@@ -268,18 +272,18 @@ func ServeOn(name string, tools []Tool, in io.Reader, out io.Writer) error {
} }
// Beside the loop, never in it: a tool that emits waits for the runtime's answer, which // Beside the loop, never in it: a tool that emits waits for the runtime's answer, which
// arrives on the line this loop reads next — and calls do not queue behind a slow one. // arrives on the line this loop reads next — and calls do not queue behind a slow one.
go func(id any, t Tool, args map[string]any, caller, call string) { go func(id any, t Tool, args map[string]any, caller, call, ask string) {
if args == nil { if args == nil {
args = map[string]any{} args = map[string]any{}
} }
result, err := runAs(t, caller, call, args) result, err := runAs(t, inFlight{caller, call, ask}, args)
if err != nil { if err != nil {
c.say(map[string]any{"id": id, "result": map[string]any{"content": []map[string]any{{"type": "text", "text": err.Error()}}, "isError": true}}) c.say(map[string]any{"id": id, "result": map[string]any{"content": []map[string]any{{"type": "text", "text": err.Error()}}, "isError": true}})
return return
} }
text, _ := json.Marshal(result) text, _ := json.Marshal(result)
c.say(map[string]any{"id": id, "result": map[string]any{"content": []map[string]any{{"type": "text", "text": string(text)}}}}) c.say(map[string]any{"id": id, "result": map[string]any{"content": []map[string]any{{"type": "text", "text": string(text)}}}})
}(id, t, p.Arguments, callerIn(p.Meta), callIn(p.Meta)) }(id, t, p.Arguments, callerIn(p.Meta), callIn(p.Meta), askIn(p.Meta))
case "mesh/event": case "mesh/event":
// One event the runtime read from this module's consumer (ADR 0198), answered once every // One event the runtime read from this module's consumer (ADR 0198), answered once every
// handler it is for has taken it; an error is answered as one, so the runtime does not // handler it is for has taken it; an error is answered as one, so the runtime does not
+36 -2
View File
@@ -19,12 +19,15 @@
package testbus package testbus
import ( import (
"fmt"
"os" "os"
"sync" "sync"
"testing" "testing"
"time" "time"
"github.com/nats-io/nats-server/v2/server" "github.com/nats-io/nats-server/v2/server"
stdio "git.novox.be/novox/mesh-sdk/go"
) )
// Version is the release of the server the tests run. // Version is the release of the server the tests run.
@@ -64,9 +67,9 @@ func Start(t testing.TB) *server.Server {
t.Fatalf("a bus for this test could not be made: %v", err) t.Fatalf("a bus for this test could not be made: %v", err)
} }
go s.Start() go s.Start()
if !s.ReadyForConnections(30 * time.Second) { if bound := SetupBound(t); !s.ReadyForConnections(bound) {
s.Shutdown() s.Shutdown()
t.Fatal("a bus for this test did not come up within 30s") Starved(t, fmt.Sprintf("a bus for this test did not come up within %s", bound))
} }
t.Cleanup(func() { t.Cleanup(func() {
s.Shutdown() s.Shutdown()
@@ -74,3 +77,34 @@ func Start(t testing.TB) *server.Server {
}) })
return s return s
} }
// SetupStarved opens the one line a test prints when its setup wait on the bus passed the setup bound (design 47 H2
// §800, H-A-368): a build module reads it in the test output, never an assertion's words, and runs the level again.
const SetupStarved = stdio.SetupStarved
// levelBoundWord is the environment word a build step gives each test level its bound in, as a duration ("10m").
const levelBoundWord = "MESH_TEST_LEVEL_BOUND"
// unsetSetupBound is the setup bound of a run whose level has no bound (a developer's own run).
const unsetSetupBound = 30 * time.Second
// SetupBound is how long a test's setup may wait on the bus: half of the level's bound (MESH_TEST_LEVEL_BOUND), 30 s when
// it is unset, never a value in the test. A bound that is no duration fails the test, naming it.
func SetupBound(t testing.TB) time.Duration {
t.Helper()
word := os.Getenv(levelBoundWord)
if word == "" {
return unsetSetupBound
}
level, err := time.ParseDuration(word)
if err != nil || level <= 0 {
t.Fatalf("%s=%q is not a duration such as 10m", levelBoundWord, word)
}
return level / 2
}
// Starved fails the test with the line SetupStarved and its words: a setup wait on the bus passed SetupBound.
func Starved(t testing.TB, words string) {
t.Helper()
t.Fatalf("%s %s", SetupStarved, words)
}
+22
View File
@@ -50,6 +50,28 @@ func TestBusAnswersPublishAndKeyValueCreate(t *testing.T) {
if string(entry.Value()) != "v" { if string(entry.Value()) != "v" {
t.Errorf("read back %q, want %q", entry.Value(), "v") t.Errorf("read back %q, want %q", entry.Value(), "v")
} }
// Design 47 H2 §800, H-A-368: the setup bound is half of the level's bound, 30 s when the level has none, and a starved
// setup fails with the one line a build module reads.
t.Run("the setup bound is half the level's and a starved setup says so", func(t *testing.T) {
for _, c := range []struct {
level string
want time.Duration
fails bool
}{{"", 30 * time.Second, false}, {"10m", 5 * time.Minute, false}, {"ten", 0, true}, {"-1s", 0, true}} {
t.Setenv(levelBoundWord, c.level)
f := &failed{TB: t}
var got time.Duration
catch(f, func() { got = SetupBound(f) })
if c.fails != (f.words != "") || (!c.fails && got != c.want) {
t.Errorf("level %q: bound %s, failed %q", c.level, got, f.words)
}
}
f := &failed{TB: t}
catch(f, func() { Starved(f, "the stream did not answer within 5s") })
if f.words != "mesh: setup starved: the stream did not answer within 5s" {
t.Errorf("a starved setup said %q", f.words)
}
})
} }
// 1175/AC3, 1171/AC1: the bus is gone when the test that started it ends. // 1175/AC3, 1171/AC1: the bus is gone when the test that started it ends.
+27
View File
@@ -0,0 +1,27 @@
package testbus
import (
"fmt"
"testing"
)
// failed is a testing.TB that keeps what a helper failed with, so the helper's own failure is read, not suffered.
type failed struct {
testing.TB
words string
}
func (f *failed) Helper() {}
func (f *failed) Fatalf(format string, args ...any) {
f.words = fmt.Sprintf(format, args...)
panic(f)
}
func catch(f *failed, run func()) {
defer func() {
if r := recover(); r != nil && r != f {
panic(r)
}
}()
run()
}
+7
View File
@@ -21,6 +21,13 @@ mesh-delivery f8bbde9627255fe37bd6603a40fcce14fb61d97b modules/mesh-delivery-co
mesh-delivery d24d6a08905996841b62c723736339e809ca4625 modules/mesh-delivery-contracts/seats/git/seat.json, taken again as seat.json.captured (milestone 47/H1, C2 amended, H-A-71) mesh-delivery d24d6a08905996841b62c723736339e809ca4625 modules/mesh-delivery-contracts/seats/git/seat.json, taken again as seat.json.captured (milestone 47/H1, C2 amended, H-A-71)
mesh-delivery 6e027de59773affe80d7bf45cf49d81292893ff1 modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json, taken again as seat.json.captured (milestone 47/H1, C3) mesh-delivery 6e027de59773affe80d7bf45cf49d81292893ff1 modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json, taken again as seat.json.captured (milestone 47/H1, C3)
mesh-delivery 9a55e6e8c0faa36dd96be2d90c13e5bb42be0bf3 modules/mesh-delivery-contracts/seats/git, mesh-delivery and mesh-catalog, taken again as seat.json.captured (milestone 47/H1, through C1d) mesh-delivery 9a55e6e8c0faa36dd96be2d90c13e5bb42be0bf3 modules/mesh-delivery-contracts/seats/git, mesh-delivery and mesh-catalog, taken again as seat.json.captured (milestone 47/H1, through C1d)
mesh-delivery d2d3ebbf44fbf0362edaf78d991615f564644615 modules/mesh-delivery-contracts/seats/git/seat.json, taken again as seat.json.captured (milestone 47/H2, D5)
mesh-contracts e6ed560e48216024a0ab6851074c134e69a9bc2b seats/node-engine/seat.json, taken again as seat.json.captured (milestone 47/H2, branch feat/47-H2, H-A-452)
mesh-delivery 80ff1afacca4c1d2e61b0e31139b140645c8088b modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json, taken again as seat.json.captured (milestone 47/H2, branch feat/47-H2, H-A-452)
mesh-delivery 5e94328066198d72cf4fd5d6f1c57b6ad1c8e967 modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json, taken again as seat.json.captured (milestone 47/H2, branch feat/47-H2-i, its form 5, H-A-452)
mesh-contracts 8f2bed18e5ae219489573984fdfddee2d9550288 seats/node-engine/seat.json, taken again as seat.json.captured (milestone 47/H2, branch feat/47-H2, its form 4, H-A-452)
mesh-delivery abfe37e690885956a16fca7c31a5792849e40818 modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json, taken again as seat.json.captured (milestone 47/H2, branch feat/47-H2, H-A-452)
mesh-contracts ba5a253888ca0d7767b76ecb8b1ad7367c577662 seats/node-engine/seat.json, taken again as seat.json.captured (milestone 47/H2, branch feat/47-H2, the have's pipeline description, H-A-452)
mesh-host cdcba9ca73755854d21e4e657d7e46c32b9b5265 internal/apply/placement_guard.go mesh-host cdcba9ca73755854d21e4e657d7e46c32b9b5265 internal/apply/placement_guard.go
The two seat copies are put back the same way (git show <commit>:<file> > <file>.captured, the path kept). To move the others, from this repository's go/ directory, with the two repositories checked out beside mesh-sdk: The two seat copies are put back the same way (git show <commit>:<file> > <file>.captured, the path kept). To move the others, from this repository's go/ directory, with the two repositories checked out beside mesh-sdk:
@@ -1,11 +1,12 @@
{ {
"format": 1, "format": 1,
"form": 4,
"seat": "node-engine", "seat": "node-engine",
"scope": "node", "scope": "node",
"grain": "whole", "grain": "whole",
"domain": "Core", "domain": "Core",
"decision": "novox/hq ADR 0563", "decision": "novox/hq ADR 0563",
"description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token, or, for an event whose subject names <node>, there (composed.<node>, running.<node>.<module>): the grants part grants a node's account only its own node's subjects (ADR 0363 §2).", "description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 \u00a73, \u00a74): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token, or, for an event whose subject names <node>, there (composed.<node>, running.<node>.<module>): the grants part grants a node's account only its own node's subjects (ADR 0363 \u00a72).",
"acts": [ "acts": [
{ {
"step": "compose", "step": "compose",
@@ -15,7 +16,7 @@
"verbs": [ "verbs": [
{ {
"name": "hand-over", "name": "hand-over",
"description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 §3, §5): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.", "description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 \u00a73, \u00a75): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.",
"input": { "input": {
"properties": { "properties": {
"path": { "path": {
@@ -39,7 +40,7 @@
}, },
{ {
"name": "access-act", "name": "access-act",
"description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 §7, ADR 0563 §3, §4), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 \u00a77, ADR 0563 \u00a73, \u00a74), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.",
"input": { "input": {
"properties": { "properties": {
"access": { "access": {
@@ -68,7 +69,7 @@
}, },
{ {
"name": "judge-directories", "name": "judge-directories",
"description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 §2). Read-only: changes no owner or mode.", "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 \u00a72). Read-only: changes no owner or mode.",
"input": { "input": {
"properties": {}, "properties": {},
"type": "object" "type": "object"
@@ -80,7 +81,7 @@
}, },
{ {
"name": "setuid-search", "name": "setuid-search",
"description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 §2); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 \u00a72); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.",
"input": { "input": {
"properties": { "properties": {
"why": { "why": {
@@ -97,7 +98,7 @@
}, },
{ {
"name": "root-free", "name": "root-free",
"description": "Whether this machine is root-free (novox/hq ADR 0259 §8, ADR 0563 §6): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", "description": "Whether this machine is root-free (novox/hq ADR 0259 \u00a78, ADR 0563 \u00a76): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.",
"input": { "input": {
"properties": {}, "properties": {},
"type": "object" "type": "object"
@@ -121,7 +122,7 @@
}, },
{ {
"name": "acts", "name": "acts",
"description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 §9): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 \u00a79): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.",
"input": { "input": {
"properties": { "properties": {
"id": { "id": {
@@ -242,7 +243,7 @@
"type": "string" "type": "string"
}, },
"digest": { "digest": {
"description": "a composition's digest (sha256:…), to read that revision rather than the latest", "description": "a composition's digest (sha256:\u2026), to read that revision rather than the latest",
"type": "string" "type": "string"
}, },
"module": { "module": {
@@ -287,7 +288,7 @@
}, },
"self": { "self": {
"type": "boolean", "type": "boolean",
"description": "the node composes the module itself (ADR 0547 §2)" "description": "the node composes the module itself (ADR 0547 \u00a72)"
}, },
"backup": { "backup": {
"type": "string", "type": "string",
@@ -455,6 +456,32 @@
}, },
"description": "every resource that differs from what runs, when asked" "description": "every resource that differs from what runs, when asked"
}, },
"drift": {
"type": "array",
"description": "when the diff is asked, each directory entry of what runs that the mesh made, as its record holds, whose owner or mode on disk differ from it (H-A-392 (b), H-A-458 (2)): read-only; the engine sets it right at its next start or apply of the module",
"items": {
"type": "object",
"required": [
"id",
"path",
"drift"
],
"properties": {
"id": {
"type": "string",
"description": "the directory entry's id in the composition"
},
"path": {
"type": "string",
"description": "its path on the machine"
},
"drift": {
"type": "string",
"description": "how its owner or mode on disk differ, in words"
}
}
}
},
"own": { "own": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -517,6 +544,27 @@
"withheld-unknown": { "withheld-unknown": {
"type": "string", "type": "string",
"description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer" "description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer"
},
"withheld-parts": {
"type": "array",
"description": "each part a compose kept because its read did not answer, with why (design 08 control-verbs \u00a74, H-A-321): for the packet filter's holder the part node-packet-filter.allowed, its filter file kept as it runs",
"items": {
"type": "object",
"required": [
"part",
"why"
],
"properties": {
"part": {
"type": "string",
"description": "the read asked, as <seat>.<verb>"
},
"why": {
"type": "string",
"description": "why it did not answer, naming the holder asked"
}
}
}
} }
}, },
"required": [ "required": [
@@ -529,6 +577,63 @@
}, },
"class": "read" "class": "read"
}, },
{
"name": "composition-diff",
"description": "One module's composed values read by resource (design 47 H2 \u00a7813 (3), H-A-349 DQ-12b): given a module and a revision or a digest of its composition, the entries that differ between the composition that runs and that one, per resource, environment entries by name, a secret's value masked. Read-only. Answered by this machine's engine alone.",
"class": "read",
"input": {
"type": "object",
"required": [
"module"
],
"properties": {
"module": {
"type": "string",
"description": "the module, as placed on this machine; node for the node's own"
},
"revision": {
"type": "integer",
"description": "the revision of the module's composition key to compare with, from the revisions the bucket keeps; give it or digest"
},
"digest": {
"type": "string",
"description": "the digest (sha256:\u2026) of the composition to compare with; give it or revision"
}
}
},
"answer": {
"type": "object",
"required": [
"node",
"module",
"resources"
],
"properties": {
"node": {
"type": "string",
"description": "the node"
},
"module": {
"type": "string",
"description": "the module"
},
"running": {
"type": "string",
"description": "the digest of the composition that runs; absent when nothing runs"
},
"other": {
"$ref": "#/defs/Revision"
},
"resources": {
"type": "array",
"description": "each resource with an entry that differs; empty when none differs",
"items": {
"$ref": "#/defs/CompositionDiffResource"
}
}
}
}
},
{ {
"name": "compose", "name": "compose",
"description": "Compose this machine's modules now and say how it went, so a composition that failed, or a module held, recovers without a restart: what the pass refused or held, each with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried again. Changes only what a pass the engine makes on its own would change.", "description": "Compose this machine's modules now and say how it went, so a composition that failed, or a module held, recovers without a restart: what the pass refused or held, each with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried again. Changes only what a pass the engine makes on its own would change.",
@@ -595,7 +700,7 @@
}, },
{ {
"name": "compose-candidate", "name": "compose-candidate",
"description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 §7). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.", "description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 \u00a77). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.",
"optional": true, "optional": true,
"input": { "input": {
"properties": { "properties": {
@@ -640,7 +745,7 @@
"unready", "unready",
"not-judged" "not-judged"
], ],
"description": "the node's verdict (ADR 0593 §7, §9)" "description": "the node's verdict (ADR 0593 \u00a77, \u00a79)"
}, },
"modules": { "modules": {
"type": "array", "type": "array",
@@ -686,7 +791,7 @@
{ {
"name": "manifest-reads", "name": "manifest-reads",
"optional": true, "optional": true,
"description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 §3) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.", "description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 \u00a73) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.",
"input": { "input": {
"type": "object", "type": "object",
"properties": {} "properties": {}
@@ -720,7 +825,7 @@
"node", "node",
"stated-at" "stated-at"
], ],
"description": "what this machine's engine reads of a manifest (ADR 0618 §3)" "description": "what this machine's engine reads of a manifest (ADR 0618 \u00a73)"
}, },
"class": "read" "class": "read"
}, },
@@ -787,7 +892,7 @@
}, },
{ {
"name": "seat-list", "name": "seat-list",
"description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 \u00a77): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.",
"input": { "input": {
"type": "object", "type": "object",
"properties": {} "properties": {}
@@ -798,7 +903,7 @@
}, },
{ {
"name": "seat-list-again", "name": "seat-list-again",
"description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 \u00a77), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.",
"input": { "input": {
"type": "object", "type": "object",
"properties": {} "properties": {}
@@ -1057,6 +1162,52 @@
"$ref": "#/defs/ProcessBuilds" "$ref": "#/defs/ProcessBuilds"
}, },
"class": "read" "class": "read"
},
{
"name": "converged",
"description": "The node's convergence state, which the node-engine keeps (ADR 0168, ADR 0683; design 33 control-verbs \u00a710): adopted or converged, since when it became so, for an adopted node the kind of the firewall found, and the node's links as the engine classifies them: the tunnel's interface and the outward links (design 47 H-A-325). Read-only: the holder of node-packet-filter asks it at its start and at every allow and disallow, and refuses when it does not answer.",
"class": "read",
"input": {
"type": "object",
"properties": {}
},
"answer": {
"type": "object",
"required": [
"state",
"tunnel",
"outward"
],
"properties": {
"state": {
"type": "string",
"enum": [
"adopted",
"converged"
],
"description": "the node's mode: adopted (the found firewall's terms) or converged (the mesh's own filter)"
},
"since": {
"type": "string",
"description": "when the node became so, RFC 3339; absent where the engine recorded no time for it"
},
"found": {
"type": "string",
"description": "the kind of the firewall found, for an adopted node"
},
"tunnel": {
"type": "string",
"description": "the private network's tunnel interface on this node, as the engine's filter render names it"
},
"outward": {
"type": "array",
"items": {
"type": "string"
},
"description": "the links of this node that face outside, as the engine classifies them for its filter render (ADR 0140); an allowance with no interface never opens one"
}
}
}
} }
], ],
"events": [ "events": [
@@ -1205,6 +1356,14 @@
"type": "boolean", "type": "boolean",
"description": "the move changes the build alone" "description": "the move changes the build alone"
}, },
"run": {
"type": "string",
"description": "the composition run's pipeline sequence, in decimal, the module was applied from (design 47 H2 §813 (1), H-A-388): a restarted engine applies no older run again"
},
"pipeline": {
"type": "string",
"description": "the pipeline of the want the module was applied from, its key <branch>.<source>, beside its run (H-A-429 (1), H-A-458 (1)): a want's run is compared with this run only when the want's branch is the same, the key without its last .<source>; absent for a want in none"
},
"kept": { "kept": {
"type": "array", "type": "array",
"items": { "items": {
@@ -1696,7 +1855,7 @@
"description": "one finding of the observer that wrote it" "description": "one finding of the observer that wrote it"
} }
], ],
"description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 §2, ADR 0636 §1); today `machine.<node>.seat-list-unread`" "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 \u00a72, ADR 0636 \u00a71); today `machine.<node>.seat-list-unread`"
}, },
{ {
"name": "bounds", "name": "bounds",
@@ -1708,7 +1867,7 @@
"key": "<what>.<id>", "key": "<what>.<id>",
"value": { "value": {
"type": "object", "type": "object",
"description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G §560, A-77)", "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G \u00a7560, A-77)",
"properties": { "properties": {
"v": { "v": {
"type": "integer", "type": "integer",
@@ -1815,7 +1974,7 @@
}, },
"auto": { "auto": {
"type": "boolean", "type": "boolean",
"description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4)" "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 \u00a74)"
} }
}, },
"required": [ "required": [
@@ -1825,7 +1984,7 @@
"at", "at",
"state" "state"
], ],
"description": "one act asked through the seat, as acts reads it (ADR 0563 §9)" "description": "one act asked through the seat, as acts reads it (ADR 0563 \u00a79)"
}, },
"ActSaid": { "ActSaid": {
"type": "object", "type": "object",
@@ -1870,7 +2029,7 @@
"state", "state",
"node" "node"
], ],
"description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 §1)" "description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 \u00a71)"
}, },
"Acts": { "Acts": {
"type": "object", "type": "object",
@@ -1961,7 +2120,7 @@
"at", "at",
"why" "why"
], ],
"description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 §4)" "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 \u00a74)"
}, },
"Module": { "Module": {
"type": "object", "type": "object",
@@ -2061,7 +2220,7 @@
"why", "why",
"judged" "judged"
], ],
"description": "the engine's root-free verdict (ADR 0563 §6)" "description": "the engine's root-free verdict (ADR 0563 \u00a76)"
}, },
"Said": { "Said": {
"type": "object", "type": "object",
@@ -2106,7 +2265,7 @@
}, },
"SeatList": { "SeatList": {
"type": "object", "type": "object",
"description": "what an engine holds of the seat list (novox/hq ADR 0636 §7)", "description": "what an engine holds of the seat list (novox/hq ADR 0636 \u00a77)",
"properties": { "properties": {
"status": { "status": {
"type": "object", "type": "object",
@@ -2451,6 +2610,10 @@
"type": "string" "type": "string"
} }
}, },
"declaration-reads": {
"type": "integer",
"description": "the declaration Version its engine reads (design 47 H2 §813 (12), H-A-416 (2), H-A-419): the composer writes this node's declaration at the lower of its own Version and this one, 1 when none is stated"
},
"runner-capabilities": { "runner-capabilities": {
"type": "array", "type": "array",
"items": { "items": {
@@ -3160,7 +3323,7 @@
}, },
"Running": { "Running": {
"type": "object", "type": "object",
"description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit", "description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 \u00a72), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit",
"properties": { "properties": {
"v": { "v": {
"type": "integer", "type": "integer",
@@ -3331,6 +3494,52 @@
"step", "step",
"since" "since"
] ]
},
"CompositionDiffEntry": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "the entry: an environment entry by its name, else the part of the resource that differs"
},
"running": {
"type": "string",
"description": "its value in the running composition; absent where the running one lacks it or the value is a secret"
},
"other": {
"type": "string",
"description": "its value in the other composition; absent where the other lacks it or the value is a secret"
},
"masked": {
"type": "boolean",
"description": "the value is a secret, so neither value is given"
}
},
"description": "one entry that differs between the running composition and the other"
},
"CompositionDiffResource": {
"type": "object",
"required": [
"resource",
"entries"
],
"properties": {
"resource": {
"type": "string",
"description": "the resource, as the composition names it"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/CompositionDiffEntry"
},
"description": "the entries of the resource that differ"
}
},
"description": "one resource with the entries of it that differ"
} }
} }
} }
@@ -5,7 +5,7 @@
"grain": "whole", "grain": "whole",
"domain": "Delivery", "domain": "Delivery",
"decision": "novox/hq ADR 0111", "decision": "novox/hq ADR 0111",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer.", "description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer.",
"delivers": "git", "delivers": "git",
"verbs": [ "verbs": [
{ {
@@ -48,6 +48,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what pull answers; error and error-kind alone when it fails" "description": "what pull answers; error and error-kind alone when it fails"
@@ -96,6 +104,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what branch answers; error and error-kind alone when it fails" "description": "what branch answers; error and error-kind alone when it fails"
@@ -126,6 +142,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails", "description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails",
@@ -171,9 +195,9 @@
"tags": { "tags": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "$ref": "#/defs/Tag"
}, },
"description": "the tags of this page" "description": "the tags of this page, each with the commit it names (design 47 H2 §796)"
}, },
"page": { "page": {
"type": "integer", "type": "integer",
@@ -193,6 +217,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what tags answers; error and error-kind alone when it fails" "description": "what tags answers; error and error-kind alone when it fails"
@@ -201,7 +233,7 @@
}, },
{ {
"name": "trees", "name": "trees",
"description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part.", "description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part. A directory named in files or paths that the commit does not hold answers the error kind not-found (design 47 H2 §796).",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -284,6 +316,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what trees answers; error and error-kind alone when it fails" "description": "what trees answers; error and error-kind alone when it fails"
@@ -350,6 +390,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what file answers; error and error-kind alone when it fails" "description": "what file answers; error and error-kind alone when it fails"
@@ -410,6 +458,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what contains answers; error and error-kind alone when it fails" "description": "what contains answers; error and error-kind alone when it fails"
@@ -464,6 +520,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what statuses answers; error and error-kind alone when it fails" "description": "what statuses answers; error and error-kind alone when it fails"
@@ -546,6 +610,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what status answers; error and error-kind alone when it fails" "description": "what status answers; error and error-kind alone when it fails"
@@ -607,6 +679,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what comment answers; error and error-kind alone when it fails" "description": "what comment answers; error and error-kind alone when it fails"
@@ -668,6 +748,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what view answers; error and error-kind alone when it fails" "description": "what view answers; error and error-kind alone when it fails"
@@ -730,6 +818,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what note answers; error and error-kind alone when it fails" "description": "what note answers; error and error-kind alone when it fails"
@@ -738,7 +834,7 @@
}, },
{ {
"name": "merge-pull", "name": "merge-pull",
"description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H \u00a7734, \u00a7735, \u00a7766; ADR 0682 \u00a71, \u00a72). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.", "description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H §734, §735, §766; ADR 0682 §1, §2). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -805,6 +901,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what merge-pull answers at the call's end; error and error-kind alone when it fails" "description": "what merge-pull answers at the call's end; error and error-kind alone when it fails"
@@ -815,7 +919,7 @@
{ {
"name": "tag", "name": "tag",
"class": "act", "class": "act",
"description": "Write the git tag of a released version, go/vMAJOR.MINOR.PATCH, at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.", "description": "Write the git tag of a released version, <directory>/vMAJOR.MINOR.PATCH for a Go package (design 47 H2 §796), at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -856,6 +960,14 @@
}, },
"error-kind": { "error-kind": {
"$ref": "#/defs/ErrorKind" "$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
} }
}, },
"description": "what tag answers; error and error-kind alone when it fails" "description": "what tag answers; error and error-kind alone when it fails"
@@ -1259,7 +1371,7 @@
"name": "calls", "name": "calls",
"template": "state", "template": "state",
"history": 1, "history": 1,
"description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H \u00a7766, H-A-47)", "description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H §766, H-A-47)",
"key-forms": [ "key-forms": [
{ {
"key": "call.<call>", "key": "call.<call>",
@@ -1328,7 +1440,7 @@
"description": "its page on the forge" "description": "its page on the forge"
} }
}, },
"description": "one pull request as the forge holds it; never its description (ADR 0659 \u00a71)", "description": "one pull request as the forge holds it; never its description (ADR 0659 §1)",
"required": [ "required": [
"repository", "repository",
"number", "number",
@@ -1361,7 +1473,7 @@
"description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused" "description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused"
} }
}, },
"description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 \u00a71): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one", "description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 §1): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one",
"required": [ "required": [
"mergeable", "mergeable",
"protected", "protected",
@@ -1471,9 +1583,10 @@
"enum": [ "enum": [
"refused", "refused",
"not-found", "not-found",
"failed" "failed",
"away"
], ],
"description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed" "description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed; away, a part the holder depends on (the forge, its store) is away, with part naming what did not answer and words: a caller reads it as a transport fault and calls again (design 47 H2 §776)"
}, },
"FailedStep": { "FailedStep": {
"type": "object", "type": "object",
@@ -1529,7 +1642,7 @@
}, },
"MemberOutcome": { "MemberOutcome": {
"type": "object", "type": "object",
"description": "one member of a merge call and where it stands (design 47 H \u00a7766, H-A-22)", "description": "one member of a merge call and where it stands (design 47 H §766, H-A-22)",
"properties": { "properties": {
"repository": { "repository": {
"type": "string" "type": "string"
@@ -1564,7 +1677,7 @@
}, },
"Call": { "Call": {
"type": "object", "type": "object",
"description": "one merge call, written before its first merge and updated as each member merges (design 47 H \u00a7766)", "description": "one merge call, written before its first merge and updated as each member merges (design 47 H §766)",
"properties": { "properties": {
"by": { "by": {
"type": "string", "type": "string",
@@ -1640,12 +1753,30 @@
"head", "head",
"state" "state"
] ]
},
"Tag": {
"type": "object",
"description": "a tag and the commit it names (design 47 H2 §796)",
"properties": {
"tag": {
"type": "string"
},
"commit": {
"type": "string",
"description": "the commit it names, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"tag",
"commit"
]
} }
}, },
"bodies": { "bodies": {
"MergeCalled": { "MergeCalled": {
"type": "object", "type": "object",
"description": "a merge call's members merged or refused, said once by the forge module (design 47 H \u00a7736, \u00a7767)", "description": "a merge call's members merged or refused, said once by the forge module (design 47 H §736, §767)",
"properties": { "properties": {
"call": { "call": {
"type": "string", "type": "string",
@@ -1702,7 +1833,7 @@
}, },
"refused": { "refused": {
"type": "array", "type": "array",
"description": "one per member not merged after every member was judged (design 47 H \u00a7767)", "description": "one per member not merged after every member was judged (design 47 H §767)",
"items": { "items": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -1732,5 +1863,6 @@
"members" "members"
] ]
} }
} },
"form": 2
} }
@@ -253,6 +253,49 @@
}, },
"class": "read" "class": "read"
}, },
{
"name": "seat-list",
"class": "read",
"description": "The trunk's seat list as the mesh holds it, the object of the holder's objects seat-lists of that digest (design 47 H2 §814, §820; H-A-441, H-A-443): its digest and size, then its bytes (the definitions resolved, a JSON array in the form of a composer request's seats, sorted by seat) in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds. A validate run's asker fills the request's seats from these bytes. Reads only.",
"input": {
"type": "object",
"properties": {
"call": {
"type": "string",
"description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements",
"minLength": 1
}
},
"required": [
"call"
]
},
"answer": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the seat list's sha256, the object's name in seat-lists"
},
"size": {
"type": "integer",
"minimum": 0,
"description": "the seat list's size in bytes"
},
"chunks": {
"type": "integer",
"minimum": 0,
"description": "how many chunks are sent"
}
},
"required": [
"digest",
"size",
"chunks"
]
},
"chunks": true
},
{ {
"name": "revision", "name": "revision",
"description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).", "description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).",
@@ -312,7 +355,7 @@
}, },
{ {
"name": "registrations", "name": "registrations",
"description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed.", "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed. Filtered by module or repository while it reads and paged by the cursor next, at most 768 KB a page (design 47 H2 §806, §811).",
"input": { "input": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -323,6 +366,14 @@
"history": { "history": {
"type": "boolean", "type": "boolean",
"description": "with every version of the one module" "description": "with every version of the one module"
},
"repository": {
"type": "string",
"description": "only the registrations of this repository, <owner>/<name>, applied while reading (design 47 H2 §806)"
},
"next": {
"type": "string",
"description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)"
} }
} }
}, },
@@ -344,6 +395,18 @@
}, },
"fill": { "fill": {
"$ref": "#/defs/Fill" "$ref": "#/defs/Fill"
},
"capped": {
"type": "boolean",
"description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §806)"
},
"total": {
"type": "integer",
"description": "how many registrations the filters hold in all (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)"
} }
}, },
"required": [ "required": [
@@ -657,6 +720,32 @@
"source": { "source": {
"type": "integer" "type": "integer"
}, },
"call": {
"type": "string",
"description": "what made the revision, as the revision's call names it (design 47 H-A-212, H-A-213); absent for a candidate's"
},
"call-kind": {
"type": "string",
"enum": [
"take-in",
"release",
"take-in-again",
"recompute"
],
"description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217); absent for a candidate's"
},
"module": {
"type": "string",
"description": "for call-kind release, the module released (H-A-215)"
},
"version": {
"type": "string",
"description": "for call-kind release, the version released (H-A-215)"
},
"repository": {
"type": "string",
"description": "for call-kind take-in-again, the repository taken in again (H-A-215)"
},
"group": { "group": {
"type": "string" "type": "string"
}, },
@@ -1448,6 +1537,13 @@
"$ref": "#/defs/Registration" "$ref": "#/defs/Registration"
}, },
"description": "a module's registration" "description": "a module's registration"
},
{
"key": "source.<owner>.<name>",
"value": {
"$ref": "#/defs/Registration"
},
"description": "a source-only registration of a repository with no module (design 47 H2 §815)"
} }
] ]
}, },
@@ -1462,6 +1558,13 @@
"$ref": "#/defs/Registration" "$ref": "#/defs/Registration"
}, },
"description": "one version of a module's registration" "description": "one version of a module's registration"
},
{
"key": "source.<owner>.<name>.<version>",
"value": {
"$ref": "#/defs/Registration"
},
"description": "one version of a source-only registration (design 47 H2 §815)"
} }
] ]
}, },
@@ -1594,6 +1697,10 @@
"type": "string", "type": "string",
"description": "its manifest's verdict: accepted, refused or held" "description": "its manifest's verdict: accepted, refused or held"
}, },
"class": {
"type": "string",
"description": "core or leaf: core when its manifest claims a seat, leaf when it claims none; an entry without it reads as leaf (design 47 H2 H-A-394, H-A-431)"
},
"fp": { "fp": {
"type": "string", "type": "string",
"description": "its fingerprint (src2: and 64 hex digits); absent when it has none" "description": "its fingerprint (src2: and 64 hex digits); absent when it has none"
@@ -1871,6 +1978,32 @@
"type": "integer", "type": "integer",
"description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto" "description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto"
}, },
"call": {
"type": "string",
"description": "what made the revision (design 47 H-A-212, H-A-213): a take-in's the gate's call its source revision names, a re-pin's release of <module> <version>, a take-in again's take-in again of <repository>; absent for a candidate's"
},
"call-kind": {
"type": "string",
"enum": [
"take-in",
"release",
"take-in-again",
"recompute"
],
"description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217): a take-in's, a re-pin's on a module's release, a take-in again's, a recompute's that moved a fingerprint (its call naming the reason); absent for a candidate's"
},
"module": {
"type": "string",
"description": "for call-kind release, the module released (H-A-215)"
},
"version": {
"type": "string",
"description": "for call-kind release, the version released (H-A-215)"
},
"repository": {
"type": "string",
"description": "for call-kind take-in-again, the repository taken in again (H-A-215)"
},
"group": { "group": {
"type": "string", "type": "string",
"description": "a candidate's group" "description": "a candidate's group"
@@ -1927,6 +2060,10 @@
"$ref": "#/defs/TakeInEntry" "$ref": "#/defs/TakeInEntry"
}, },
"description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover" "description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover"
},
"base": {
"type": "integer",
"description": "the newest kept revision of its branch below it, which the take-in that wrote it pinned for its pipeline: the base of the validate step's case before (design 47 H-A-147, H-A-151, H-A-154); absent on the branch's first take-in"
} }
}, },
"required": [ "required": [
@@ -2078,14 +2215,15 @@
}, },
"Registration": { "Registration": {
"type": "object", "type": "object",
"description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve", "description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve; or a source-only registration of a repository with no module (design 47 H2 §815): its origin, one watched branch, its policy and its check, naming no module and no path, kept under source.<owner>.<name>",
"properties": { "properties": {
"v": { "v": {
"type": "integer", "type": "integer",
"description": "the layout version" "description": "the layout version"
}, },
"module": { "module": {
"type": "string" "type": "string",
"description": "the module; absent for a source-only registration"
}, },
"origin": { "origin": {
"type": "string", "type": "string",
@@ -2093,7 +2231,7 @@
}, },
"path": { "path": {
"type": "string", "type": "string",
"description": "the path of its manifest in the repository" "description": "the path of its manifest in the repository; absent for a source-only registration"
}, },
"branches": { "branches": {
"type": "array", "type": "array",
@@ -2121,12 +2259,14 @@
"at": { "at": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time"
},
"check": {
"$ref": "#/defs/SourceCheck",
"description": "for a source-only registration, the one step its heads run (design 47 H2 §815)"
} }
}, },
"required": [ "required": [
"module",
"origin", "origin",
"path",
"branches", "branches",
"policy" "policy"
] ]
@@ -2157,9 +2297,10 @@
"placed", "placed",
"review required", "review required",
"unknown module", "unknown module",
"nothing moves" "nothing moves",
"holds-manifest"
], ],
"description": "why no ask was raised" "description": "why no ask was raised; holds-manifest: a source-only registration whose repository holds a module.json at its root or under modules/ at the branch's head (design 47 H2 §815; H-A-450)"
}, },
"words": { "words": {
"type": "string", "type": "string",
@@ -2469,6 +2610,34 @@
"ref", "ref",
"language" "language"
] ]
},
"SourceCheck": {
"type": "object",
"description": "the check of a source-only registration: a build seat and a step kind, run at the repository's root, never a free command (design 47 H2 §815)",
"properties": {
"seat": {
"type": "string",
"enum": [
"node-build-go",
"node-build-node",
"node-build-image"
],
"description": "the build seat that runs it"
},
"step": {
"type": "string",
"enum": [
"lint",
"unit",
"integration"
],
"description": "the step kind"
}
},
"required": [
"seat",
"step"
]
} }
}, },
"bodies": { "bodies": {
@@ -2567,5 +2736,6 @@
"call" "call"
] ]
} }
} },
"form": 5
} }
@@ -9,7 +9,7 @@
"verbs": [ "verbs": [
{ {
"name": "deliveries", "name": "deliveries",
"description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group.", "description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group. Filtered by repository, module, outcome and since while it reads, at most 768 KB a page, capped saying the rest is read from the cursor next (design 47 H2 §811).",
"input": { "input": {
"properties": { "properties": {
"all": { "all": {
@@ -31,13 +31,55 @@
"state": { "state": {
"description": "one state, e.g. delivering or held", "description": "one state, e.g. delivering or held",
"type": "string" "type": "string"
},
"module": {
"type": "string",
"description": "only the deliveries that move this module, applied while reading (design 47 H2 §811)"
},
"outcome": {
"type": "string",
"description": "only the deliveries that ended with this outcome, applied while reading (design 47 H2 §811)"
},
"since": {
"type": "string",
"format": "date-time",
"description": "only the deliveries opened at or after this time, applied while reading (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)"
} }
}, },
"type": "object" "type": "object"
}, },
"answer": { "answer": {
"type": "object", "type": "object",
"description": "what deliveries answers, as its description says" "description": "what deliveries answers, as its description says",
"properties": {
"deliveries": {
"type": "array",
"items": {
"type": "object",
"description": "one delivery's record, as the gate keeps it"
},
"description": "this page's deliveries, the open ones first, then the newest"
},
"capped": {
"type": "boolean",
"description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811)"
},
"total": {
"type": "integer",
"description": "how many deliveries the filters hold in all (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)"
}
},
"required": [
"deliveries"
]
}, },
"class": "read" "class": "read"
}, },
@@ -196,7 +238,7 @@
"name": "record-opened", "name": "record-opened",
"body": { "body": {
"type": "object", "type": "object",
"description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)", "description": "a delivery record opened for one source revision of a merge call (design 47 H §737)",
"properties": { "properties": {
"record": { "record": {
"type": "string", "type": "string",
@@ -319,7 +361,7 @@
"subject": "source-moved.<branch>.<source>", "subject": "source-moved.<branch>.<source>",
"body": { "body": {
"type": "object", "type": "object",
"description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)", "description": "a source revision of a watched branch, named once per merge call (design 47 H §737)",
"properties": { "properties": {
"v": { "v": {
"type": "integer" "type": "integer"
@@ -337,7 +379,7 @@
}, },
"start": { "start": {
"type": "boolean", "type": "boolean",
"description": "true only for a branch's first revision (design 47 H \u00a7768)" "description": "true only for a branch's first revision (design 47 H §768)"
}, },
"heads": { "heads": {
"type": "array", "type": "array",
@@ -448,7 +490,7 @@
}, },
"call": { "call": {
"type": "string", "type": "string",
"description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)" "description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H §737, H-A-33)"
} }
}, },
"required": [ "required": [
@@ -512,7 +554,7 @@
"name": "heads", "name": "heads",
"template": "state", "template": "state",
"history": 1, "history": 1,
"description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H \u00a7740)", "description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H §740)",
"key-forms": [ "key-forms": [
{ {
"key": "<repository>.<branch>", "key": "<repository>.<branch>",
@@ -607,6 +649,10 @@
"type": "string", "type": "string",
"format": "date-time", "format": "date-time",
"description": "when the gate first said it" "description": "when the gate first said it"
},
"record": {
"type": "string",
"description": "the delivery record the act is for, by its source revision, <branch>.<source>; absent on an act said before it was named, which bridge_owed_again by record never finds (design 47 H2 §807, H-A-432)"
} }
}, },
"required": [ "required": [
@@ -672,5 +718,6 @@
"head" "head"
] ]
} }
} },
"form": 2
} }
+1
View File
@@ -1,3 +1,4 @@
buscompose/nats.go: mesh-grants
catalogue/environment_into.go: node-environment catalogue/environment_into.go: node-environment
catalogue/environment_into.go: node-login-shell catalogue/environment_into.go: node-login-shell
catalogue/environment_into.go: node-power catalogue/environment_into.go: node-power
+7 -6
View File
@@ -25,9 +25,10 @@ func (k KeptSource) Get(key string) (*Entry, bool, error) {
return &Entry{Value: e.Value, Revision: e.Revision, Written: e.At}, true, nil return &Entry{Value: e.Value, Revision: e.Revision, Written: e.At}, true, nil
} }
// Page is the values after a key in one request (stdio.KeptState.Page), as FirstView prefers them to Get per key. // Page is the values after the opaque cursor in one request (stdio.KeptState.Page, in the order the bus wrote them),
func (k KeptSource) Page(after string, maxBytes int, budget time.Duration) ([]KeyedEntry, string, error) { // as FirstView prefers them to Get per key, and the cursor that continues them.
p, err := k.State.Page(after, maxBytes, budget) func (k KeptSource) Page(cursor string, maxBytes int, budget time.Duration) ([]KeyedEntry, string, error) {
p, err := k.State.Page(cursor, maxBytes, budget)
if err != nil { if err != nil {
return nil, "", err return nil, "", err
} }
@@ -61,10 +62,10 @@ func FirstViewTool(owner, name, state, words string, values, marks Source, now f
Name: name, Name: name,
Description: fmt.Sprintf("The first view of %s's state %s (novox/hq ADR 0615, ADR 0621): %s Each value whole by key, at the revision "+ Description: fmt.Sprintf("The first view of %s's state %s (novox/hq ADR 0615, ADR 0621): %s Each value whole by key, at the revision "+
"the owner said its views family up to, so a reader then follows the events on that family and asks again only on a gap in "+ "the owner said its views family up to, so a reader then follows the events on that family and asks again only on a gap in "+
"revisions. One page at a time: next is the key to ask after for the rest.", "revisions. One page at a time: hand next back as after for the rest.",
owner, state, words), owner, state, words),
Input: map[string]any{"type": "object", "properties": map[string]any{ Input: map[string]any{"type": "object", "properties": map[string]any{
"after": map[string]any{"type": "string", "description": "the key the page before ended at (its next); none starts at the first"}}}, "after": map[string]any{"type": "string", "description": "the next of the page before; none starts at the first"}}},
Run: func(args map[string]any) (any, error) { Run: func(args map[string]any) (any, error) {
after, _ := args["after"].(string) after, _ := args["after"].(string)
return FirstView(owner, state, values, marks, strings.TrimSpace(after), now()) return FirstView(owner, state, values, marks, strings.TrimSpace(after), now())
@@ -87,7 +88,7 @@ func ReadTool(owner, name, state, words string, values, marks Source, now func()
"key": map[string]any{"type": "string", "description": "one key: its value and revision"}, "key": map[string]any{"type": "string", "description": "one key: its value and revision"},
"history": map[string]any{"type": "boolean", "description": "with key: every value the state keeps for it, oldest first"}, "history": map[string]any{"type": "boolean", "description": "with key: every value the state keeps for it, oldest first"},
"values": map[string]any{"type": "boolean", "description": "a page of values whole by key"}, "values": map[string]any{"type": "boolean", "description": "a page of values whole by key"},
"after": map[string]any{"type": "string", "description": "with values: the key the page before ended at"}}}, "after": map[string]any{"type": "string", "description": "with values: the next of the page before"}}},
Run: func(args map[string]any) (any, error) { Run: func(args map[string]any) (any, error) {
key, _ := args["key"].(string) key, _ := args["key"].(string)
after, _ := args["after"].(string) after, _ := args["after"].(string)
+7 -5
View File
@@ -174,7 +174,7 @@ func DecodeMark(data []byte) (Mark, error) {
} }
// Answer is a first view, or one page of an ordinary read: the state's values by key, from After on, at the revision // Answer is a first view, or one page of an ordinary read: the state's values by key, from After on, at the revision
// of the state the owner said up to (Mark) before it read them; Next is the key to ask after for the rest, empty when // of the state the owner said up to (Mark) before it read them; Next is handed back as after for the rest, empty when
// the answer is whole. A reader keeps the first page's revision: a value on a later page may be newer, and the events // the answer is whole. A reader keeps the first page's revision: a value on a later page may be newer, and the events
// after that revision bring every key to its newest in order. // after that revision bring every key to its newest in order.
type Answer struct { type Answer struct {
@@ -222,15 +222,17 @@ type KeyedEntry struct {
Entry Entry
} }
// Pager is a Source that answers many values in one request: the values in key order after a key, as many as fit // Pager is a Source that answers many values in one request: the values after an opaque cursor (empty: from the
// maxBytes or the time budget and at least one, and the key to ask after for the rest. FirstView uses it when its source has it, unless // start), as many as fit maxBytes or the time budget and at least one, and the cursor that continues them, empty at
// the end (design 47 H2 §779). FirstView uses it when its source has it, unless
// it answers errors.Is(err, errors.ErrUnsupported), when it reads per key. // it answers errors.Is(err, errors.ErrUnsupported), when it reads per key.
type Pager interface { type Pager interface {
Page(after string, maxBytes int, budget time.Duration) ([]KeyedEntry, string, error) Page(cursor string, maxBytes int, budget time.Duration) ([]KeyedEntry, string, error)
} }
// FirstView answers one page of state from its owner's source: the mark first, so no change after the revision it // FirstView answers one page of state from its owner's source: the mark first, so no change after the revision it
// answers at is missed, then the values in key order after after, until PageBytes or PageBudget. A state not said yet (no mark) // answers at is missed, then the values after after (the next of the page before: the Pager's cursor, or with a source
// that reads per key the last key, in key order), until PageBytes or PageBudget. A state not said yet (no mark)
// answers revision 0: a first view of whatever it holds, which the reader takes as a gap at the first event. // answers revision 0: a first view of whatever it holds, which the reader takes as a gap at the first event.
func FirstView(owner, state string, values, marks Source, after string, now time.Time) (Answer, error) { func FirstView(owner, state string, values, marks Source, after string, now time.Time) (Answer, error) {
a := Answer{V: Version, Owner: owner, State: state, Values: map[string]json.RawMessage{}, At: now.UTC()} a := Answer{V: Version, Owner: owner, State: state, Values: map[string]json.RawMessage{}, At: now.UTC()}
+46
View File
@@ -1441,6 +1441,52 @@ func (s *pagedSource) Page(after string, _ int, _ time.Duration) ([]KeyedEntry,
func TestViews(t *testing.T) { func TestViews(t *testing.T) {
t.Run("Views", subViews) t.Run("Views", subViews)
t.Run("StdioWriterPublishesAndListensThroughTheModulesOwnPlumbing", subStdioWriterPublishesAndListensThroughTheModulesOwnPlumbing) t.Run("StdioWriterPublishesAndListensThroughTheModulesOwnPlumbing", subStdioWriterPublishesAndListensThroughTheModulesOwnPlumbing)
// Design 47 H2 §782: one process reader's pictures are safe at once: gets, keys and watches from many goroutines while
// the owner's events change the picture and further views are followed, under the race detector.
t.Run("one process reader serves concurrent reads", func(t *testing.T) {
made := time.Date(2026, 11, 22, 0, 0, 0, 0, time.UTC)
r := &ProcessReader{Module: "reader", Call: func(string, any) (json.RawMessage, error) {
return json.Marshal(Answer{V: Version, Owner: "o", State: "s", Revision: 1, Created: made, Values: map[string]json.RawMessage{"a": json.RawMessage(`1`)}})
}}
p, err := r.Follow("o", "s", "o.o_read")
if err != nil {
t.Fatal(err)
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
if err := p.Follower().Start(ctx); err != nil {
t.Fatal(err)
}
var wg sync.WaitGroup
wg.Add(1)
go func() {
defer wg.Done()
for i := range 200 {
p.Follower().Apply(Event{V: Version, Owner: "o", State: "s", Key: fmt.Sprintf("k%d", i%7), Revision: uint64(i + 2), Created: made, Value: json.RawMessage(`2`)})
}
}()
for i := range 16 {
wg.Add(1)
go func() {
defer wg.Done()
w, err := p.Watch(ctx, ">")
if err != nil {
t.Error(err)
return
}
defer w.Stop()
for range 20 {
_, _ = p.Get(ctx, "a")
_, _ = p.Keys(ctx)
_ = r.Followers()
}
if _, err := r.Follow("o", fmt.Sprintf("s%d", i), "o.o_read"); err != nil {
t.Error(err)
}
}()
}
wg.Wait()
})
} }
type putRecorder struct{ puts map[string][]byte } type putRecorder struct{ puts map[string][]byte }
+16
View File
@@ -7,6 +7,10 @@
"": { "": {
"name": "@novox/mesh-sdk", "name": "@novox/mesh-sdk",
"version": "0.1.19", "version": "0.1.19",
"dependencies": {
"blakejs": "1.2.1",
"tweetnacl": "1.0.3"
},
"devDependencies": { "devDependencies": {
"@types/node": "^22.0.0", "@types/node": "^22.0.0",
"typescript": "^5.6.0" "typescript": "^5.6.0"
@@ -22,6 +26,18 @@
"undici-types": "~6.21.0" "undici-types": "~6.21.0"
} }
}, },
"node_modules/blakejs": {
"version": "1.2.1",
"resolved": "https://registry.npmjs.org/blakejs/-/blakejs-1.2.1.tgz",
"integrity": "sha512-QXUSXI3QVc/gJME0dBpXrag1kbzOqCjCX8/b54ntNyW6sjtoqxqRk3LTmXzaJoh71zMsDCjM+47jS7XiwN/+fQ==",
"license": "MIT"
},
"node_modules/tweetnacl": {
"version": "1.0.3",
"resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-1.0.3.tgz",
"integrity": "sha512-6rt+RN7aOi1nGMyC4Xa5DdYiukl2UWCbcJft7YhxReBGQD7OAM8Pbxw6YMo4r2diNEA8FEmu32YOn9rhaiE5yw==",
"license": "Unlicense"
},
"node_modules/typescript": { "node_modules/typescript": {
"version": "5.9.3", "version": "5.9.3",
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+6 -1
View File
@@ -15,7 +15,8 @@
"./state": "./dist/state/index.js", "./state": "./dist/state/index.js",
"./callers": "./dist/callers/index.js", "./callers": "./dist/callers/index.js",
"./runtime": "./dist/runtime/index.js", "./runtime": "./dist/runtime/index.js",
"./views": "./dist/views/index.js" "./views": "./dist/views/index.js",
"./seal": "./dist/seal/index.js"
}, },
"files": [ "files": [
"dist" "dist"
@@ -29,5 +30,9 @@
"devDependencies": { "devDependencies": {
"@types/node": "^22.0.0", "@types/node": "^22.0.0",
"typescript": "^5.6.0" "typescript": "^5.6.0"
},
"dependencies": {
"blakejs": "1.2.1",
"tweetnacl": "1.0.3"
} }
} }
+48 -1
View File
@@ -17,6 +17,12 @@ export const META_CALLER = "mesh/caller";
/** Where in a `tools/call`'s `_meta` the runtime names the id of the call in flight (`buscalls.MetaCall`). */ /** Where in a `tools/call`'s `_meta` the runtime names the id of the call in flight (`buscalls.MetaCall`). */
export const META_CALL = "mesh/call"; export const META_CALL = "mesh/call";
/**
* Where in a `tools/call`'s `_meta` the runtime names the ask id a kept call carried (the Go side's `stdio.MetaAsk`;
* design 47 H2 §775, H-A-351): what a holder takes the ask once by.
*/
export const META_ASK = "mesh/ask";
// A bus user's name: `<node>.<module>`, `person.<name>`, `controller`; anything else is no caller. // A bus user's name: `<node>.<module>`, `person.<name>`, `controller`; anything else is no caller.
const busUser = /^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$/; const busUser = /^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$/;
// A call's id: one subject-safe token. // A call's id: one subject-safe token.
@@ -25,6 +31,7 @@ const callID = /^[A-Za-z0-9_-]{1,128}$/;
interface InFlight { interface InFlight {
readonly caller: string; readonly caller: string;
readonly call: string; readonly call: string;
readonly ask: string;
} }
// The caller and the call's id of every call while its tool runs, by the arguments object that call was handed. // The caller and the call's id of every call while its tool runs, by the arguments object that call was handed.
@@ -42,12 +49,18 @@ export function callIn(meta: unknown): string {
return typeof s === "string" && callID.test(s) ? s : ""; return typeof s === "string" && callID.test(s) ? s : "";
} }
/** The ask id a `tools/call`'s `_meta` names, or empty: one subject-safe token, as a call's id is. */
export function askIn(meta: unknown): string {
const s = meta && typeof meta === "object" ? (meta as Record<string, unknown>)[META_ASK] : undefined;
return typeof s === "string" && callID.test(s) ? s : "";
}
/** /**
* Run `run` with the caller and the call's id `meta` names held for `args` while it runs: the stdio session does this * Run `run` with the caller and the call's id `meta` names held for `args` while it runs: the stdio session does this
* for every `tools/call`. * for every `tools/call`.
*/ */
export async function runAs<T>(meta: unknown, args: object, run: () => Promise<T>): Promise<T> { export async function runAs<T>(meta: unknown, args: object, run: () => Promise<T>): Promise<T> {
calls.set(args, { caller: callerIn(meta), call: callIn(meta) }); calls.set(args, { caller: callerIn(meta), call: callIn(meta), ask: askIn(meta) });
try { try {
return await run(); return await run();
} finally { } finally {
@@ -65,6 +78,11 @@ export function callIdOf(args: object | undefined | null): string {
return (args && calls.get(args)?.call) || ""; return (args && calls.get(args)?.call) || "";
} }
/** The ask id the call that was handed `args` carried (H-A-351), or empty. Valid while the tool runs. */
export function askIdOf(args: object | undefined | null): string {
return (args && calls.get(args)?.ask) || "";
}
/** /**
* A module's trusted list of who may call it (ADR 0459 §2): an entry is a module (on any machine), exactly * A module's trusted list of who may call it (ADR 0459 §2): an entry is a module (on any machine), exactly
* `<machine>.<module>`, or exactly `person.<name>`. A wildcard is no entry and an unproven caller never matches. * `<machine>.<module>`, or exactly `person.<name>`. A wildcard is no entry and an unproven caller never matches.
@@ -212,3 +230,32 @@ export function readDefinitionCallers(verb: string, value: unknown, cls?: string
} }
return value as string[]; return value as string[];
} }
/**
* The seat error kind a holder answers when a part it depends on is away (design 47 H2 §776; H-A-349 DQ-15): its
* answer's `error-kind`, beside `part` (what did not answer) and `words`; a caller reads it as a transport fault and
* calls again at the kept-call pace. The Go side's `busretry.ErrorKindAway`.
*/
export const ERROR_KIND_AWAY = "away";
/** A holder's answer of the kind away: `error` and `error-kind` as each seat's error answer has them, with `part` and `words`. */
export interface AwayAnswer {
readonly error: string;
readonly "error-kind": typeof ERROR_KIND_AWAY;
readonly part: string;
readonly words: string;
}
/** The answer of the kind away a holder gives when `part` does not answer (the Go side's `busretry.AwayAnswer`). */
export function awayAnswer(part: string, words: string): AwayAnswer {
return { error: `away: ${part} does not answer: ${words}`, "error-kind": ERROR_KIND_AWAY, part, words };
}
/** The part and words a verb's answer says when its `error-kind` is away, else undefined (the Go side's `busretry.AwayIn`). */
export function awayIn(answer: unknown): { part: string; words: string } | undefined {
if (!answer || typeof answer !== "object" || Array.isArray(answer)) return undefined;
const a = answer as Record<string, unknown>;
if (a["error-kind"] !== ERROR_KIND_AWAY) return undefined;
const str = (v: unknown) => (typeof v === "string" ? v : "");
return { part: str(a.part), words: str(a.words) || str(a.error) };
}
+1
View File
@@ -16,3 +16,4 @@ export * as state from "./state/index.js";
export * as runtime from "./runtime/index.js"; export * as runtime from "./runtime/index.js";
export * as callers from "./callers/index.js"; export * as callers from "./callers/index.js";
export * as views from "./views/index.js"; export * as views from "./views/index.js";
export * as seal from "./seal/index.js";
+181
View File
@@ -0,0 +1,181 @@
// The mesh's sealed box in TypeScript (novox/hq ADR 0183, ADR 0206; design 47 H2, lead answer H-A-407), the same
// box as the Go package seal (go/seal) byte for byte: a value sealed to one recipient's public key, which only that
// recipient's private key opens. X25519 for the agreement, HKDF-SHA256 for the key, AES-256-GCM for the box.
//
// A box is `{ v: 1, eph, iv, tag, ct }`, every field standard base64; `eph` is the one-time public key as SPKI DER.
// The key is derived with the salt eph-DER ‖ the recipient's raw public key and the info "novox-mesh sealed box v1",
// so a box cannot be re-addressed to another key. Keys travel as PEM: the public key as SPKI ("PUBLIC KEY"), the
// private key as PKCS #8 ("PRIVATE KEY"). Node's crypto only.
//
// sealAnonymous is the other seal, the NaCl anonymous box (libsodium's crypto_box_seal) the vault's intake opens:
// X25519 and XSalsa20-Poly1305 under a one-time key, the nonce BLAKE2b-24 of the one-time public key ‖ the recipient's,
// the box the one-time public key ‖ the sealed bytes. From two pinned libraries, tweetnacl and blakejs (H-A-407).
import {
createCipheriv,
createDecipheriv,
createPrivateKey,
createPublicKey,
diffieHellman,
generateKeyPairSync,
hkdfSync,
randomBytes,
type KeyObject,
} from "node:crypto";
import nacl from "tweetnacl";
import blakejs from "blakejs";
/** A value sealed to one recipient, as it travels in JSON (go/seal's Box). */
export interface Box {
v: number;
eph: string;
iv: string;
tag: string;
ct: string;
}
/** A recipient's keypair as the two PEM strings it is kept and sent as (go/seal's KeyPair). */
export interface KeyPair {
publicKey: string;
privateKey: string;
}
/** The only box version open opens. */
export const VERSION = 1;
const INFO = "novox-mesh sealed box v1";
// PKCS #8 DER of an X25519 private key is this prefix and the key's 32 raw bytes (RFC 8410).
const X25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex");
/** A fresh X25519 keypair, PEM-encoded. */
export function generateKeyPair(): KeyPair {
const { publicKey, privateKey } = generateKeyPairSync("x25519");
return {
publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
};
}
/** Seals plaintext to the recipient's PEM public key, with a fresh one-time key and iv. */
export function seal(plaintext: string, recipientPEM: string): Box {
const eph = generateKeyPairSync("x25519").privateKey;
return sealWith(plaintext, recipientPEM, eph, randomBytes(12));
}
/**
* sealWith is seal with its two sources of randomness given: the one-time key (a KeyObject, or its 32 raw bytes) and
* the iv. Exported for the byte-for-byte tests against the Go package's vectors; a caller seals with seal.
*/
export function sealWith(plaintext: string, recipientPEM: string, eph: KeyObject | Uint8Array, iv: Uint8Array): Box {
const recipient = publicFromPEM(recipientPEM);
const ephKey = eph instanceof Uint8Array ? privateFromRaw(eph) : eph;
const secret = diffieHellman({ privateKey: ephKey, publicKey: recipient });
const ephDER = createPublicKey(ephKey).export({ type: "spki", format: "der" });
const cipher = createCipheriv("aes-256-gcm", boxKey(secret, ephDER, rawPublic(recipient)), iv);
const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
const b64 = (b: Uint8Array) => Buffer.from(b).toString("base64");
return { v: VERSION, eph: b64(ephDER), iv: b64(iv), tag: b64(cipher.getAuthTag()), ct: b64(ct) };
}
/**
* Opens a box with the recipient's PEM private key. It throws for a box sealed to another key, one changed in any
* field, or one of another version.
*/
export function open(box: Box, privatePEM: string): string {
if (box.v !== VERSION) {
throw new Error(`a sealed box of version ${box.v}, not ${VERSION}`);
}
const priv = privateFromPEM(privatePEM);
const ephDER = Buffer.from(box.eph, "base64");
let eph: KeyObject;
try {
eph = createPublicKey({ key: ephDER, format: "der", type: "spki" });
} catch (e) {
throw new Error(`the box's eph: ${(e as Error).message}`);
}
if (eph.asymmetricKeyType !== "x25519") {
throw new Error("the box's eph is not an X25519 key");
}
const secret = diffieHellman({ privateKey: priv, publicKey: eph });
const iv = Buffer.from(box.iv, "base64");
const tag = Buffer.from(box.tag, "base64");
if (iv.length !== 12 || tag.length !== 16) {
throw new Error("the box does not open with this key");
}
try {
const decipher = createDecipheriv("aes-256-gcm", boxKey(secret, ephDER, rawPublic(createPublicKey(priv))), iv);
decipher.setAuthTag(tag);
return Buffer.concat([decipher.update(Buffer.from(box.ct, "base64")), decipher.final()]).toString("utf8");
} catch {
throw new Error("the box does not open with this key");
}
}
function publicFromPEM(pem: string): KeyObject {
let k: KeyObject;
try {
k = createPublicKey(pem);
} catch {
throw new Error("not a PEM public key");
}
if (k.asymmetricKeyType !== "x25519") {
throw new Error("not an X25519 public key");
}
return k;
}
function privateFromPEM(pem: string): KeyObject {
let k: KeyObject;
try {
k = createPrivateKey(pem);
} catch {
throw new Error("not a PEM private key");
}
if (k.asymmetricKeyType !== "x25519") {
throw new Error("not an X25519 private key");
}
return k;
}
function privateFromRaw(raw: Uint8Array): KeyObject {
if (raw.length !== 32) {
throw new Error("an X25519 private key is 32 bytes");
}
return createPrivateKey({ key: Buffer.concat([X25519_PKCS8_PREFIX, raw]), format: "der", type: "pkcs8" });
}
// rawPublic is an X25519 public key's 32 raw bytes: the end of its SPKI DER.
function rawPublic(k: KeyObject): Buffer {
const der = k.export({ type: "spki", format: "der" });
return der.subarray(der.length - 32);
}
// boxKey is HKDF-SHA256 (RFC 5869) for one 32-byte block, salted with eph-DER ‖ the recipient's raw public key.
function boxKey(secret: Uint8Array, ephDER: Uint8Array, recipientRaw: Uint8Array): Buffer {
return Buffer.from(hkdfSync("sha256", secret, Buffer.concat([ephDER, recipientRaw]), INFO, 32));
}
/**
* Seals value to sealTo, a raw X25519 public key in standard base64 (the vault's `seal_to`), in the NaCl anonymous
* box, answered in standard base64: what golang.org/x/crypto/nacl/box's SealAnonymous makes and OpenAnonymous opens.
*/
export function sealAnonymous(value: string | Uint8Array, sealTo: string): string {
return sealAnonymousWith(value, sealTo, nacl.randomBytes(nacl.box.secretKeyLength));
}
/**
* sealAnonymousWith is sealAnonymous with its one-time private key given (32 bytes). Exported for the byte-for-byte
* tests against the Go package's bytes; a caller seals with sealAnonymous.
*/
export function sealAnonymousWith(value: string | Uint8Array, sealTo: string, ephSecret: Uint8Array): string {
const recipient = new Uint8Array(Buffer.from(sealTo.trim(), "base64"));
if (recipient.length !== nacl.box.publicKeyLength) {
throw new Error("the key to seal to is not a raw X25519 public key in base64");
}
const eph = nacl.box.keyPair.fromSecretKey(new Uint8Array(ephSecret));
const nonce = blakejs.blake2b(Buffer.concat([eph.publicKey, recipient]), undefined, nacl.box.nonceLength);
const message = typeof value === "string" ? new Uint8Array(Buffer.from(value, "utf8")) : new Uint8Array(value);
const sealed = nacl.box(message, nonce, recipient, eph.secretKey);
return Buffer.concat([eph.publicKey, sealed]).toString("base64");
}
+44
View File
@@ -133,6 +133,50 @@ function withinOneCall(key: string, value: unknown): void {
} }
} }
/** The state a holder of a kept call keeps the ids of the asks it took in (design 47 H2 §775, §820): Go's `stdio.TakenState`. */
export const TAKEN_STATE = "taken";
/** The key an ask taken from `seat` is kept under in TAKEN_STATE: `<seat>.<ask>`. */
export function takenKey(seat: string, ask: string): string {
return `${seat}.${ask}`;
}
/** The code of the runtime's refusal of a create whose key has a value (Go's `stdio.CodeChanged`). */
const CODE_CHANGED = -32010;
/**
* Whether this holder takes the ask `ask` of `seat` now (design 47 H2 §775; H-A-359), as Go's `KeptState.TakeOnce`: the
* first time it is given it is created under takenKey with the ask's bound as its time to live (the runtime's
* `mesh/state.create`) and this resolves true; given again within the bound, false, and the holder acts once.
* `stateName` is the holder's TAKEN_STATE, declared `key-ttl`.
*/
export async function takeOnce(seat: string, ask: string, boundMs: number, stateName = TAKEN_STATE): Promise<boolean> {
if (!ask || /[.*> ]/.test(ask)) throw new Error(`taking an ask of ${seat}: ${JSON.stringify(ask)} is not an ask id: an ask id holds no dot and no wildcard, naming one key and no other`);
if (!seat || /[.*> ]/.test(seat)) throw new Error(`taking the ask ${ask}: ${JSON.stringify(seat)} is not a seat's name`);
refusedUnannounced(stateName);
try {
await boundChannel().ask("mesh/state.create", {
state: stateName,
key: takenKey(seat, ask),
value: { seat, ask },
ttl_seconds: Math.max(1, Math.floor(boundMs / 1000)),
});
return true;
} catch (e) {
if ((e as { code?: number }).code === CODE_CHANGED) return false;
throw e;
}
}
/**
* Remove what the deleted object `name` left behind in the object store `objects` (by its local name), its chunks,
* through the runtime's `mesh/objects.delete`, which purges them again when asked again (H-A-366): the Go side's `busstate.Objects.Purge`. A bundle never opens a
* connection of its own for it.
*/
export async function purgeObject(objects: string, name: string): Promise<void> {
await boundChannel().ask("mesh/objects.delete", { objects, name });
}
/** A state this module keeps (by its local name) or reads (`<module>.<name>`). */ /** A state this module keeps (by its local name) or reads (`<module>.<name>`). */
export function state<T = unknown>(name: string): State<T> { export function state<T = unknown>(name: string): State<T> {
const bound = (): StateChannel => { const bound = (): StateChannel => {
+3 -6
View File
@@ -154,7 +154,9 @@ test("asked for again, a retired consumer is created again and announced re-enab
} }
}); });
test("five passes are not enough: the same set must also hold for stableForMs", async () => { test("five passes are not enough: the same set must also hold for stableForMs, ten minutes by default", async () => {
const { STABLE_FOR_MS } = await import("../dist/provider-loop/index.js");
assert.equal(STABLE_FOR_MS, 10 * 60_000);
const HOLD = 400; const HOLD = 400;
const w = await world(["a", "b", "c"], { stableForMs: HOLD }); const w = await world(["a", "b", "c"], { stableForMs: HOLD });
try { try {
@@ -170,11 +172,6 @@ test("five passes are not enough: the same set must also hold for stableForMs",
} }
}); });
test("the default hold is ten minutes", async () => {
const { STABLE_FOR_MS } = await import("../dist/provider-loop/index.js");
assert.equal(STABLE_FOR_MS, 10 * 60_000);
});
test("an adapter without retire is MARK-ONLY: nothing changes in the backend, remove only on delete", async () => { test("an adapter without retire is MARK-ONLY: nothing changes in the backend, remove only on delete", async () => {
const w = await world(["a", "b", "c"], { retire: false, del: false }); const w = await world(["a", "b", "c"], { retire: false, del: false });
try { try {
+35 -1
View File
@@ -670,7 +670,7 @@ test("the provider loop is named for what it is, and its old name stays an alias
await newTest6(); // a TypeScript bundle's value over one call's limit fails at once, namin await newTest6(); // a TypeScript bundle's value over one call's limit fails at once, namin
}); });
import { allows, refusal, parseCallers, parseVerbCallers, parseConfiguredVerbCallers, readDefinitionCallers, moduleOf, UNPROVEN } from "../dist/callers/index.js"; import { allows, refusal, parseCallers, parseVerbCallers, parseConfiguredVerbCallers, readDefinitionCallers, moduleOf, UNPROVEN, runAs, askIdOf, META_ASK, awayAnswer, awayIn } from "../dist/callers/index.js";
import { Follower, statusTools, keepStatus, statusKey, viewWaitsFinding, type Answer, type Status } from "../dist/views/index.js"; import { Follower, statusTools, keepStatus, statusKey, viewWaitsFinding, type Answer, type Status } from "../dist/views/index.js";
// callers and verb callers judge a proved caller by the Go side's rules (ADR 0459 §2, ADR 0627 §2) // callers and verb callers judge a proved caller by the Go side's rules (ADR 0459 §2, ADR 0627 §2)
@@ -698,6 +698,17 @@ async function newTest1(): Promise<void> {
for (const [cls, want] of byClass) assert.deepEqual(readDefinitionCallers("list", undefined, cls), want, String(cls)); for (const [cls, want] of byClass) assert.deepEqual(readDefinitionCallers("list", undefined, cls), want, String(cls));
assert.deepEqual(readDefinitionCallers("register", ["seat:mesh-broker"], "act"), ["seat:mesh-broker"]); assert.deepEqual(readDefinitionCallers("register", ["seat:mesh-broker"], "act"), ["seat:mesh-broker"]);
assert.throws(() => parseCallers('{"callers":["a"],"more":1}'), /unknown field "more"/); assert.throws(() => parseCallers('{"callers":["a"],"more":1}'), /unknown field "more"/);
// design 47 H2 §775, H-A-351: the ask id a kept call carried is the runtime's to name under mesh/ask, never the arguments'
for (const [meta, args, want] of [[{ [META_ASK]: "build-7Hq2" }, {}, "build-7Hq2"], [{}, { [META_ASK]: "forged" }, ""], [{ [META_ASK]: "a.b" }, {}, ""]] as const) {
const a = { ...args };
assert.equal(await runAs(meta, a, async () => askIdOf(a)), want, JSON.stringify(meta));
assert.equal(askIdOf(a), "", "no ask once the call ended");
}
// design 47 H2 §776, DQ-15: the kind away is answered and read as the Go side does
assert.deepEqual(awayIn(JSON.parse(JSON.stringify(awayAnswer("the forge's store", "401")))), { part: "the forge's store", words: "401" });
assert.equal(awayAnswer("p", "w")["error-kind"], "away");
assert.equal(awayIn({ error: "no", "error-kind": "refused" }), undefined);
assert.deepEqual(awayIn({ error: "the store is down", "error-kind": "away" }), { part: "", words: "the store is down" });
const verbs = parseVerbCallers('{"pull":["*"],"merge-pull":["mesh-delivery-forge-bridge"],"comment":["operator"]}', ["pull", "merge-pull", "comment"], {}); const verbs = parseVerbCallers('{"pull":["*"],"merge-pull":["mesh-delivery-forge-bridge"],"comment":["operator"]}', ["pull", "merge-pull", "comment"], {});
assert.equal(refusal(verbs, "pull", "ace.anyone"), undefined); assert.equal(refusal(verbs, "pull", "ace.anyone"), undefined);
@@ -1023,4 +1034,27 @@ async function newTest5(): Promise<void> {
async function newTest6(): Promise<void> { async function newTest6(): Promise<void> {
const { state, CHUNK_BYTES } = await import("../dist/state/index.js"); const { state, CHUNK_BYTES } = await import("../dist/state/index.js");
await assert.rejects(state("s").put("k", { text: "x".repeat(CHUNK_BYTES) }), /512 KiB/); await assert.rejects(state("s").put("k", { text: "x".repeat(CHUNK_BYTES) }), /512 KiB/);
// design 47 H2 §775, H-A-359: a holder given the same ask id twice acts once
const { takeOnce, useStateChannel } = await import("../dist/state/index.js");
const created = new Set<string>();
const asked: unknown[] = [];
useStateChannel({
ask: async (method: string, params: unknown) => {
asked.push([method, params]);
const p = params as { key: string };
if (created.has(p.key)) throw Object.assign(new Error("exists"), { code: -32010 });
created.add(p.key);
return { revision: 1 };
},
watch: async () => {},
} as never);
assert.equal(await takeOnce("git", "a-7", 600_000), true);
assert.equal(await takeOnce("git", "a-7", 600_000), false);
assert.deepEqual(asked[0], ["mesh/state.create", { state: "taken", key: "git.a-7", value: { seat: "git", ask: "a-7" }, ttl_seconds: 600 }]);
await assert.rejects(takeOnce("git", "", 1000), /is not an ask id/);
// H-A-366: a bundle purges a deleted object's leftovers through the runtime
const { purgeObject } = await import("../dist/state/index.js");
asked.length = 0;
await purgeObject("artifacts", "pkg-1.tgz");
assert.deepEqual(asked[0], ["mesh/objects.delete", { objects: "artifacts", name: "pkg-1.tgz" }]);
} }
+49
View File
@@ -0,0 +1,49 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { seal, open, sealWith, sealAnonymous, sealAnonymousWith, generateKeyPair, type Box } from "../dist/seal/index.js";
// The seals are proven against the Go package's bytes (design 47 H2, H-A-407): the fixtures go/seal's tests make and
// check on every run.
const testdata = join(import.meta.dirname, "..", "go", "seal", "testdata");
const fixture = (name: string) => JSON.parse(readFileSync(join(testdata, name), "utf8"));
// ADR 0206's box: every box Go's seal opens (the licence manager's, the agent module's TypeScript) opens here; given
// the same one-time key and iv, seal makes Go's box byte for byte, so go/seal's Open opens it; another key and a
// changed field are refused.
test("seal and open make and open go/seal's box, and sealAnonymous Go's anonymous box, byte for byte", () => {
const f = fixture("sealed-by-licence-manager.json");
for (const s of f.sealed as { plaintext: string; box: Box }[]) {
assert.equal(open(s.box, f.recipient.privateKey), s.plaintext);
}
for (const v of f.vectors as { plaintext: string; ephPrivate: string; iv: string; box: Box }[]) {
const got = sealWith(v.plaintext, f.recipient.publicKey, Buffer.from(v.ephPrivate, "base64"), Buffer.from(v.iv, "base64"));
assert.deepEqual(got, v.box);
}
const ts = fixture("sealed-by-typescript.json");
assert.equal(open(ts.box, ts.privateKey), ts.plaintext);
const a = generateKeyPair();
const b = generateKeyPair();
const box = seal("a token", a.publicKey);
assert.equal(open(box, a.privateKey), "a token");
assert.notDeepEqual(seal("a token", a.publicKey), box);
assert.throws(() => open(box, b.privateKey), /does not open with this key/);
assert.throws(() => open({ ...box, ct: Buffer.from("changed").toString("base64") }, a.privateKey), /does not open/);
assert.throws(() => open({ ...box, v: 2 }, a.privateKey), /version 2/);
// The NaCl anonymous box the vault's intake opens: given the same one-time key, sealAnonymous makes what
// golang.org/x/crypto/nacl/box's SealAnonymous made, byte for byte; a fresh one differs and is as long.
const an = fixture("sealed-anonymous-by-go.json");
assert.ok(an.vectors.length > 0);
for (const v of an.vectors as { plaintext: string; ephSecret: string; sealed: string }[]) {
assert.equal(sealAnonymousWith(v.plaintext, an.recipient.public, Buffer.from(v.ephSecret, "base64")), v.sealed);
assert.equal(sealAnonymousWith(Buffer.from(v.plaintext, "utf8"), an.recipient.public, Buffer.from(v.ephSecret, "base64")), v.sealed);
}
const fresh = sealAnonymous("a token", an.recipient.public);
assert.notEqual(fresh, sealAnonymous("a token", an.recipient.public));
assert.equal(Buffer.from(fresh, "base64").length, 32 + 16 + "a token".length);
assert.throws(() => sealAnonymous("x", "c2hvcnQ="), /not a raw X25519 public key/);
});
+1 -3
View File
@@ -224,7 +224,7 @@ test("a failing consumer the mesh stopped asking for is said recovered when it i
} }
}); });
test("an error is classed by its words", () => { test("an error is classed by its words, and an adapter that classes its own errors is believed", async () => {
const table: Record<string, string> = { const table: Record<string, string> = {
'Keycloak token request failed: 401 {"error":"invalid_grant"}': CLASS_CREDENTIALS, 'Keycloak token request failed: 401 {"error":"invalid_grant"}': CLASS_CREDENTIALS,
'FATAL: password authentication failed for user "postgres"': CLASS_CREDENTIALS, 'FATAL: password authentication failed for user "postgres"': CLASS_CREDENTIALS,
@@ -235,9 +235,7 @@ test("an error is classed by its words", () => {
'extension "nope" is not available': CLASS_REFUSED, 'extension "nope" is not available': CLASS_REFUSED,
}; };
for (const [text, want] of Object.entries(table)) assert.equal(classOf(text), want, text); for (const [text, want] of Object.entries(table)) assert.equal(classOf(text), want, text);
});
test("an adapter that classes its own errors is believed", async () => {
const w = await world({ classify: true }); const w = await world({ classify: true });
try { try {
w.failing = new Error("anything"); w.failing = new Error("anything");