NATS4: the bus module takes and restores a restore point of a module's kept data, beside the live data

Verbs snapshot-kept and restore-kept (with aside-only and discard-aside) on the seat mesh-broker, handed to the
keeper; taken over from the join's 0480e16f and c4e88eaa, without the verbs aside and discard-aside and the tool
nats_kept, which no design line gives.

Builds: design 47 G §296, §297, §302, §337, §405

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
This commit is contained in:
2026-11-11 12:08:05 +01:00
parent c2e017a4c1
commit b6884796e7
8 changed files with 91 additions and 109 deletions
+18 -77
View File
@@ -1,9 +1,7 @@
package main
import (
"encoding/json"
"fmt"
"sort"
"strings"
"time"
@@ -16,49 +14,15 @@ import (
// the runtime's own bound on a call, so a long snapshot is answered as "handed, not ended" and read again with its request.
const keptWait = 50 * time.Second
// KeptHeld reads the keeper's state kept: the restore points it took and the data it set aside.
type KeptHeld func() ([]keeper.Point, []keeper.Aside, error)
// KeptInState is the state kept through the runtime that launched this bundle.
func KeptInState() ([]keeper.Point, []keeper.Aside, error) {
st := stdio.State(keeper.StateKept)
keys, err := st.Keys()
if err != nil {
return nil, nil, err
}
sort.Strings(keys)
var points []keeper.Point
var aside []keeper.Aside
for _, key := range keys {
e, err := st.Get(key)
if err != nil || e == nil {
continue
}
switch {
case strings.HasPrefix(key, "point."):
var p keeper.Point
if json.Unmarshal(e.Value, &p) == nil {
points = append(points, p)
}
case strings.HasPrefix(key, "aside."):
var a keeper.Aside
if json.Unmarshal(e.Value, &a) == nil {
aside = append(aside, a)
}
}
}
return points, aside, nil
}
func formOf(a map[string]any) int {
f, _ := a["form"].(float64)
return int(f)
}
// keptTools are the seat mesh-broker's verbs for a module's kept data and the bus module's tool that reads what it holds:
// keptTools are the seat mesh-broker's verbs for a module's kept data (design 47 G §405):
// each verb hands its request to the keeper, which acts on its own account, and waits for the end on the watch of its
// requests (never a poll). Asked again with `request`, a verb reads the end of the request it made.
func keptTools(rs requestStore, held KeptHeld) []stdio.Tool {
func keptTools(rs requestStore) []stdio.Tool {
entry := func(extra map[string]any) map[string]any {
in := map[string]any{"module": str("the module whose kept data it is, e.g. mesh-delivery-indexer"), "local-name": str("the kept data's local name, e.g. modules"),
"form": num("the kept data's form (a manifest field; absent reads 0)"), "fingerprint": str("the fingerprint the restore point was taken before"),
@@ -112,16 +76,6 @@ func keptTools(rs requestStore, held KeptHeld) []stdio.Tool {
}
return nil
}
readAside := func() (any, error) {
_, aside, err := held()
if err != nil {
return nil, err
}
if aside == nil {
aside = []keeper.Aside{}
}
return map[string]any{"aside": aside}, nil
}
return []stdio.Tool{
{Name: "mesh-broker.snapshot-kept",
Description: "Take the restore point of one module's kept data on the bus (milestone G, design 47): the data whole as the server's own snapshot, the position of each durable consumer the module reads with, and the catch-up tool the newer manifest declares, kept by the bus module's keeper. Answers the directory the restore point is in. Handed to the keeper, recorded as a hand act.",
@@ -131,41 +85,28 @@ func keptTools(rs requestStore, held KeptHeld) []stdio.Tool {
return point(a, r)
})},
{Name: "mesh-broker.restore-kept",
Description: "Restore one module's kept data on the bus from a restore point beside the live data, never over it (design 47): the live data is snapshotted into a set-aside directory under a name of its own and then removed from the bus, the restore point's streams are put in its place and the module's other consumers are set back to their positions. Answers what was set aside and the catch-up tool the restore point carries. Handed to the keeper, recorded as a hand act.",
Input: entry(map[string]any{"from": str("the directory the restore point was restored to, an absolute path")}),
Description: "Restore one module's kept data on the bus from a restore point beside the live data, never over it (design 47 G §405): the live data is snapshotted into a set-aside directory under a name of its own and then removed from the bus, the restore point's streams are put in its place and the module's other consumers are set back to their positions. With `aside-only` it sets the live data aside and restores nothing; with `discard-aside`, naming data set aside, it removes that data and restores nothing. Answers what was set aside and the catch-up tool the restore point carries. Handed to the keeper, recorded as a hand act.",
Input: entry(map[string]any{"from": str("the directory the restore point was restored to, an absolute path"),
"aside-only": map[string]any{"type": "boolean", "description": "set the live data aside and restore nothing"},
"discard-aside": str("the id of data set aside: remove it and restore nothing")}),
Run: run(keeper.VerbRestoreKept, func(a map[string]any, r *keeper.Request) error {
if id := arg(a, "discard-aside"); id != "" {
r.Verb, r.From = keeper.VerbDiscardAside, id
return nil
}
if b, _ := a["aside-only"].(bool); b {
r.AsideOnly = true
r.Module, r.Local = arg(a, "module"), arg(a, "local-name")
if r.Module == "" || r.Local == "" {
return fmt.Errorf("aside-only is of one kept data: a module and its local name")
}
return nil
}
r.From = arg(a, "from")
if r.From == "" {
return fmt.Errorf("a restore names the directory the restore point is in")
}
return point(a, r)
})},
{Name: "mesh-broker.discard-aside",
Description: "Remove the data a restore set aside, by its id (from `aside`), only on a person's call: it says who and why, and the keeper records the hand act before it removes anything.",
Input: map[string]any{"id": str("the id of the data set aside"), "why": str("why, in plain words: kept with the act"), "request": str("a request made before: its end is read")},
Run: run(keeper.VerbDiscardAside, func(a map[string]any, r *keeper.Request) error {
r.From = arg(a, "id")
if r.From == "" {
return fmt.Errorf("discard-aside names the id of the data set aside")
}
return nil
})},
{Name: "mesh-broker.aside", Description: "The data restores set aside, each with its module, kept data, size, when, who and why: what a person decides to discard.",
Run: func(map[string]any) (any, error) { return readAside() }},
{Name: "nats_kept",
Description: "What the bus module holds of its modules' kept data besides the live data: every restore point it took (module, kept data, form, the fingerprint it was taken before, its consumers' positions, the catch-up tool, its size) and the data a restore set aside. Read from the keeper's state kept.",
Run: func(map[string]any) (any, error) {
points, aside, err := held()
if err != nil {
return nil, err
}
if points == nil {
points = []keeper.Point{}
}
if aside == nil {
aside = []keeper.Aside{}
}
return map[string]any{"points": points, "aside": aside}, nil
}},
}
}
+13 -8
View File
@@ -33,9 +33,8 @@ func TestTheKeptDataVerbsAreHandedToTheKeeperAndReadBack(t *testing.T) {
return &r
},
}
aside := []keeper.Aside{{ID: "idx.modules.1", Module: "idx", Local: "modules", Bytes: 12}}
tools := map[string]stdio.Tool{}
for _, tl := range keptTools(rs, func() ([]keeper.Point, []keeper.Aside, error) { return nil, aside, nil }) {
for _, tl := range keptTools(rs) {
tools[tl.Name] = tl
}
for _, verb := range KeptVerbs {
@@ -53,10 +52,11 @@ func TestTheKeptDataVerbsAreHandedToTheKeeperAndReadBack(t *testing.T) {
t.Errorf("answered %+v: the request for form 1 before abc, for the caller the runtime proved, with the directory the keeper answered", r)
}
for name, args := range map[string]map[string]any{
"mesh-broker.snapshot-kept": {"module": "idx", "local-name": "modules", "fingerprint": "abc"},
"mesh-broker.restore-kept": {"module": "idx", "local-name": "modules", "fingerprint": "abc", "why": "revert"},
"mesh-broker.discard-aside": {"why": "x"},
"mesh-broker.snapshot-kept": {"module": "idx", "local-name": "modules", "fingerprint": "abc"},
"mesh-broker.restore-kept": {"module": "idx", "local-name": "modules", "fingerprint": "abc", "why": "revert"},
"mesh-broker.restore-kept#aside-only": {"aside-only": true, "why": "x"},
} {
name, _, _ = strings.Cut(name, "#")
if _, err := tools[name].Run(args); err == nil {
t.Errorf("%s with %v was handed to the keeper", name, args)
}
@@ -65,9 +65,14 @@ func TestTheKeptDataVerbsAreHandedToTheKeeperAndReadBack(t *testing.T) {
"from": "/restored/f0-abc", "why": "revert"}); err != nil || out.(*keeper.Request).From != "/restored/f0-abc" {
t.Errorf("restore answered %+v (%v)", out, err)
}
read, err := tools["mesh-broker.aside"].Run(nil)
if err != nil || !strings.Contains(strings.ReplaceAll(strings.TrimSpace(toJSON(read)), " ", ""), `"id":"idx.modules.1"`) {
t.Errorf("aside answered %v (%v)", read, err)
// `aside-only` sets the live data aside and restores nothing; `discard-aside` removes the data set aside (§405).
if out, err := tools["mesh-broker.restore-kept"].Run(map[string]any{"module": "idx", "local-name": "modules", "aside-only": true, "why": "revert"}); err != nil ||
!out.(*keeper.Request).AsideOnly || out.(*keeper.Request).Verb != keeper.VerbRestoreKept {
t.Errorf("aside-only answered %+v (%v)", out, err)
}
if out, err := tools["mesh-broker.restore-kept"].Run(map[string]any{"discard-aside": "idx.modules.1", "why": "operator's call"}); err != nil ||
out.(*keeper.Request).Verb != keeper.VerbDiscardAside || out.(*keeper.Request).From != "idx.modules.1" {
t.Errorf("discard-aside answered %+v (%v)", out, err)
}
}
+3 -3
View File
@@ -166,10 +166,10 @@ func main() {
// bus holds against what was asked, and what no manifest asks for. Its acting verbs (create, apply, recreate, drop) are
// the keeper's own work, on its own account alone (keeper.go), so no other account, the tool runner's included, holds
// them.
var ReadingVerbs = []string{"list", "show", "check", "orphans", "aside"}
var ReadingVerbs = []string{"list", "show", "check", "orphans"}
// KeptVerbs are the seat mesh-broker's verbs for a module's kept data (keptools.go): each handed to the keeper.
var KeptVerbs = []string{"snapshot-kept", "restore-kept", "discard-aside"}
var KeptVerbs = []string{"snapshot-kept", "restore-kept"}
// Events are the seat mesh-broker's events (ADR 0595 §6, ADR 0620 §2): said on the seat's subjects on the shared events stream
// and kept in full on the bus module's own stream broker-events (BROKER_EVENTS), which `history` reads (keep.go).
@@ -195,5 +195,5 @@ func allTools() []stdio.Tool {
out = append(out, readTools(jsz, LiveMsgGet(LiveBus()))...)
requests := RequestsInState()
out = append(out, requestTools(requests)...)
return append(out, keptTools(requests, KeptInState)...)
return append(out, keptTools(requests)...)
}