assigner: the key form of the state inputs is the assigner's own; an ask's key holds digest and time (A-465b)

The state inputs leaves the seat mesh-wants' definition (seatgen regenerated, no hand
edit). An ask's key holds {digest, at}; the sweep deletes an ask's key a day after its
time and an input with its object once no ask's key names it; keys of the old form
<time>.<digest> go by the time they carry, never earlier.

Builds: design 47 G A-465a, A-465b
This commit is contained in:
2026-11-17 11:05:12 +01:00
parent 4cdf14680e
commit 9849c49920
6 changed files with 136 additions and 170 deletions
@@ -25,6 +25,8 @@ import (
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/stateobjects"
"mesh-delivery-assigner/internal/buckets"
)
// A step's input by its digest (design 47 G §354, §712, A-237, A-243): the assigner keeps the input of each composition step
@@ -48,10 +50,28 @@ const (
// inputsAskPrefix opens the keys that name an input by the id of the ask it was kept for: ask.<id>, the id escaped as a name,
// holding the digest of the input the ask uses, so the build seat's step-ended of that ask finds it.
inputsAskPrefix = "ask."
// inputsAtPrefix opens the keys that say when an input was last written: at.<digest>, the time in inputsTime.
inputsAtPrefix = "at."
)
// inputAsk is what an ask's key holds (A-465b): the digest of the input the ask uses and the time the ask wrote it, in inputsTime.
type inputAsk struct {
Digest string `json:"digest"`
At string `json:"at"`
}
// readAsk reads an ask's key: the JSON form, or the bare key of the old form `<time>.<digest>` an earlier assigner wrote, which
// carries its time in the key itself.
func readAsk(raw []byte) (digest string, at time.Time) {
var a inputAsk
if json.Unmarshal(raw, &a) == nil && a.Digest != "" {
at, _ = time.Parse(inputsTime, a.At)
return a.Digest, at
}
digest = string(raw)
t, _, _ := strings.Cut(digest, ".")
at, _ = time.Parse(inputsTime, t)
return digest, at
}
// isDigest is whether a key is an input's own key: 64 hex digits.
func isDigest(key string) bool {
if len(key) != 64 {
@@ -76,9 +96,9 @@ type inputKeeper struct {
used func() (int64, error)
}
// keep keeps the exact bytes of the input of the ask under their sha256, after sweeping the inputs more than a day old among the 20
// oldest, and names the digest for the ask's id; it answers the digest. The same bytes asked again are the same one input, its
// last write renewed (A-465a).
// keep keeps the exact bytes of the input of the ask under their sha256, after sweeping, and names the digest and the time in the
// ask's key; it answers the digest. The same bytes asked again are the same one input (A-465a, A-465b). The ask's key is written
// first, so a sweep never finds the input unnamed.
func (k *inputKeeper) keep(ask string, body []byte) (string, error) {
if ask == "" {
return "", errors.New("name the ask the input is kept for")
@@ -87,46 +107,42 @@ func (k *inputKeeper) keep(ask string, body []byte) (string, error) {
k.logf("inputs: the keys older than a day are not all deleted: %v", err)
}
digest := digestOf(body)
have, err := k.vals.KV.Get(meshwants.InputsByDigestKey(digest))
raw, err := json.Marshal(inputAsk{Digest: digest, At: k.now().UTC().Format(inputsTime)})
if err != nil {
return "", err
}
if have == nil {
if k.used != nil {
used, err := k.used()
if err != nil {
return "", fmt.Errorf("the fill of the state %s is not read, so no input is kept: %w", meshwants.StateInputs, err)
}
if used+int64(len(body)) > inputsCap {
return "", fmt.Errorf("the state %s is at its cap of %d MiB (%d bytes kept), so the ask's input of %d bytes is refused",
meshwants.StateInputs, inputsCap>>20, used, len(body))
}
askKey := inputsAskPrefix + keys.EscapeName(ask)
if err := k.vals.KV.Create(askKey, raw); err != nil && !errors.Is(err, stateobjects.ErrChanged) {
return "", err
}
have, err := k.vals.KV.Get(digest)
if err != nil {
return "", err
}
if have != nil {
return digest, nil
}
if k.used != nil {
used, err := k.used()
if err == nil && used+int64(len(body)) > inputsCap {
err = fmt.Errorf("the state %s is at its cap of %d MiB (%d bytes kept), so the ask's input of %d bytes is refused",
buckets.InputsState, inputsCap>>20, used, len(body))
} else if err != nil {
err = fmt.Errorf("the fill of the state %s is not read, so no input is kept: %w", buckets.InputsState, err)
}
if err := k.vals.Put(meshwants.InputsByDigestKey(digest), base64.StdEncoding.EncodeToString(body)); err != nil && !errors.Is(err, stateobjects.ErrChanged) {
if err != nil {
_ = k.vals.KV.Delete(askKey)
return "", err
}
}
at := []byte(k.now().UTC().Format(inputsTime))
e, err := k.vals.KV.Get(inputsAtPrefix + digest)
if err != nil {
return "", err
}
if e == nil {
err = k.vals.KV.Create(inputsAtPrefix+digest, at)
} else {
err = k.vals.KV.Update(inputsAtPrefix+digest, at, e.Revision)
}
if err != nil && !errors.Is(err, stateobjects.ErrChanged) {
return "", err
}
if err := k.vals.KV.Create(inputsAskPrefix+keys.EscapeName(ask), []byte(digest)); err != nil && !errors.Is(err, stateobjects.ErrChanged) {
if err := k.vals.Put(digest, base64.StdEncoding.EncodeToString(body)); err != nil && !errors.Is(err, stateobjects.ErrChanged) {
return "", err
}
return digest, nil
}
// ended removes the name of the ask from the input it used when the build seat's step-ended of that ask is heard, and deletes the
// input, with its object, when no ask that names it is left (A-465a); an ask that kept none changes nothing.
// ended removes the ask's key when the build seat's step-ended of that ask is heard, and deletes the input it named, with its
// object, when no other ask's key names it (A-465a); an ask that kept none changes nothing.
func (k *inputKeeper) ended(ask string) error {
if ask == "" {
return nil
@@ -136,27 +152,41 @@ func (k *inputKeeper) ended(ask string) error {
if err != nil || e == nil {
return err
}
digest := string(e.Value)
digest, _ := readAsk(e.Value)
if err := k.vals.KV.Delete(askKey); err != nil {
return err
}
all, err := k.vals.KV.Keys()
named, err := k.named()
if err != nil {
return err
}
if named[digest] {
return nil // another running ask still names it
}
return k.deleteInput(digest)
}
// named is the inputs some ask's key names now.
func (k *inputKeeper) named() (map[string]bool, error) {
all, err := k.vals.KV.Keys()
if err != nil {
return nil, err
}
named := map[string]bool{}
for _, key := range all {
if !strings.HasPrefix(key, inputsAskPrefix) {
continue
}
o, err := k.vals.KV.Get(key)
if err != nil {
return err
return nil, err
}
if o != nil && string(o.Value) == digest {
return nil // another running ask still names it
if o != nil {
d, _ := readAsk(o.Value)
named[d] = true
}
}
return k.deleteInput(digest)
return named, nil
}
// deleteInput deletes an input's key and the object that key names, when it names one (A-465): an owner that ends its own key
@@ -169,9 +199,6 @@ func (k *inputKeeper) deleteInput(key string) error {
if err := k.vals.KV.Delete(key); err != nil {
return err
}
if err := k.vals.KV.Delete(inputsAtPrefix + key); err != nil {
return err
}
if e == nil {
return nil
}
@@ -214,57 +241,61 @@ func (k *inputKeeper) dropAtStart() {
k.logf("inputs: %d objects of deleted keys removed at the start, %d bytes", len(dropped), bytes)
}
// sweep deletes, among the 20 oldest inputs, those last written more than a day ago, every input of the old form (a key that is not
// a digest), and a name by ask whose input is gone.
// sweep deletes, among the 20 oldest ask keys, those written more than a day ago; every input of the digest form no ask's key names
// now, with its object; a key of the old form `<time>.<digest>` a day after the time it carries; and an old-form ask key whose
// input is gone (A-465b).
func (k *inputKeeper) sweep() error {
all, err := k.vals.KV.Keys()
if err != nil {
return err
}
var errs []error
type kept struct {
type askAt struct {
key string
at time.Time
}
var inputs []kept
var asks []string
var asks []askAt
var inputs []string
for _, key := range all {
switch {
case strings.HasPrefix(key, inputsAskPrefix):
asks = append(asks, key)
case strings.HasPrefix(key, inputsAtPrefix):
case !isDigest(key):
// the form `<time>.<digest>` an earlier assigner kept, one copy per ask: ended with its object
if err := k.deleteInput(key); err != nil {
errs = append(errs, err)
if strings.HasPrefix(key, inputsAskPrefix) {
e, err := k.vals.KV.Get(key)
if err != nil || e == nil {
continue
}
default:
var at time.Time // an input with no write time is the oldest
if e, err := k.vals.KV.Get(inputsAtPrefix + key); err == nil && e != nil {
at, _ = time.Parse(inputsTime, string(e.Value))
}
inputs = append(inputs, kept{key, at})
}
}
slices.SortFunc(inputs, func(a, b kept) int { return a.at.Compare(b.at) })
if len(inputs) > inputsSwept {
inputs = inputs[:inputsSwept]
}
for _, in := range inputs {
if k.now().Sub(in.at) < inputsKeptFor {
continue
}
if err := k.deleteInput(in.key); err != nil {
errs = append(errs, err)
}
}
for _, key := range asks {
if e, err := k.vals.KV.Get(key); err == nil && e != nil {
if gone, err := k.vals.KV.Get(string(e.Value)); err == nil && gone == nil {
if err := k.vals.KV.Delete(key); err != nil {
errs = append(errs, err)
d, at := readAsk(e.Value)
if !isDigest(d) {
if gone, err := k.vals.KV.Get(d); err == nil && gone == nil {
errs = append(errs, k.vals.KV.Delete(key))
}
}
asks = append(asks, askAt{key, at})
continue
}
if !isDigest(key) {
t, _, _ := strings.Cut(key, ".")
if at, err := time.Parse(inputsTime, t); err == nil && k.now().Sub(at) >= inputsKeptFor {
errs = append(errs, k.deleteInput(key))
}
continue
}
inputs = append(inputs, key)
}
slices.SortFunc(asks, func(a, b askAt) int { return a.at.Compare(b.at) })
if len(asks) > inputsSwept {
asks = asks[:inputsSwept]
}
for _, a := range asks {
if !a.at.IsZero() && k.now().Sub(a.at) >= inputsKeptFor {
errs = append(errs, k.vals.KV.Delete(a.key))
}
}
named, err := k.named()
if err != nil {
return errors.Join(append(errs, err)...)
}
for _, key := range inputs {
if !named[key] {
errs = append(errs, k.deleteInput(key))
}
}
return errors.Join(errs...)
@@ -275,7 +306,7 @@ func (k *inputKeeper) keyOf(digest string) (string, error) {
if !isDigest(digest) {
return "", nil
}
e, err := k.vals.KV.Get(meshwants.InputsByDigestKey(digest))
e, err := k.vals.KV.Get(digest)
if err != nil || e == nil {
return "", err
}
@@ -289,7 +320,7 @@ func (k *inputKeeper) body(digest string) ([]byte, error) {
}
key, err := k.keyOf(digest)
if err != nil {
return nil, fmt.Errorf("the state %s cannot be read: %w", meshwants.StateInputs, err)
return nil, fmt.Errorf("the state %s cannot be read: %w", buckets.InputsState, err)
}
if key == "" {
return nil, fmt.Errorf("the assigner keeps no input with the digest %s", digest)
@@ -357,7 +388,7 @@ func (o *inputObjects) open() (stateobjects.Objects, error) {
}
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
store, err := o.js.ObjectStore(ctx, catalogue.BusName(o.module, catalogue.StateObjectsName(meshwants.StateInputs)))
store, err := o.js.ObjectStore(ctx, catalogue.BusName(o.module, catalogue.StateObjectsName(buckets.InputsState)))
if errors.Is(err, jetstream.ErrBucketNotFound) || errors.Is(err, jetstream.ErrStreamNotFound) {
return nil, fmt.Errorf("the object store of the state inputs is not on the bus yet: %w", process.ErrNotYet)
}
@@ -408,7 +439,7 @@ func inputsOver(kv jetstream.KeyValue, js jetstream.JetStream, module string, lo
return nil
}
objects := &inputObjects{js: js, module: module}
v := stateobjects.Values{KV: stateobjects.BusKV{KV: kv}, Objects: objects, Store: catalogue.StateObjectsName(meshwants.StateInputs)}
v := stateobjects.Values{KV: stateobjects.BusKV{KV: kv}, Objects: objects, Store: catalogue.StateObjectsName(buckets.InputsState)}
used := func() (int64, error) {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
@@ -449,16 +480,21 @@ func inputsRead(k *inputKeeper) stdio.Tool {
return nil, fmt.Errorf("the inputs cannot be listed: %w", err)
}
slices.Sort(all)
lastAsk := map[string]string{} // the latest write time an ask's key names for each input
for _, key := range all {
if e, err := k.vals.KV.Get(key); err == nil && e != nil && strings.HasPrefix(key, inputsAskPrefix) {
if d, at := readAsk(e.Value); !at.IsZero() && at.Format(inputsTime) > lastAsk[d] {
lastAsk[d] = at.Format(inputsTime)
}
}
}
out := []inputSaid{}
for _, key := range all {
d, ok := meshwants.ParseInputsByDigestKey(key)
if !ok || !isDigest(key) || (want != "" && d != want) {
d := key
if !isDigest(key) || (want != "" && d != want) {
continue
}
t := ""
if e, err := k.vals.KV.Get(inputsAtPrefix + key); err == nil && e != nil {
t = string(e.Value)
}
t := lastAsk[key]
var text string
if found, err := k.vals.Get(key, &text); err != nil || !found {
continue
@@ -374,11 +374,11 @@ func TestAnInputIsKeptOncePerContentAndEndsWithItsLastAsk(t *testing.T) {
t.Fatalf("one key by the digest and one object wanted, got entry %v and %d objects", e, len(objs.objs))
}
for _, key := range keysOf(t, k) {
if !strings.HasPrefix(key, inputsAskPrefix) && !strings.HasPrefix(key, inputsAtPrefix) && key != digests[0] {
if !strings.HasPrefix(key, inputsAskPrefix) && key != digests[0] {
t.Errorf("a key %q beside the one input", key)
}
}
if e, _ := k.vals.KV.Get(inputsAskPrefix + "ask-2"); e == nil || string(e.Value) != digests[0] {
if e, _ := k.vals.KV.Get(inputsAskPrefix + "ask-2"); e == nil || !strings.Contains(string(e.Value), digests[0]) || !strings.Contains(string(e.Value), "20261117T100000Z") {
t.Errorf("the ask does not name the digest it uses: %v", e)
}
for _, ask := range []string{"ask-1", "ask-2"} {
@@ -417,17 +417,24 @@ func TestAnInputIsKeptOncePerContentAndEndsWithItsLastAsk(t *testing.T) {
if _, err := k.body(digests[0]); err == nil || len(objs.objs) != 0 {
t.Errorf("an input a day after its last write is kept (%v), %d objects", err, len(objs.objs))
}
// an input of the old form is ended with its object
// an input of the old form goes a day after the time its key carries, with its object, never earlier
old := "20261117T090000Z." + digestOf([]byte("old"))
if err := k.vals.Put(old, base64.StdEncoding.EncodeToString(bytes.Repeat([]byte{'o'}, 2<<20))); err != nil {
t.Fatal(err)
}
recent := now.Add(-time.Hour).Format(inputsTime) + "." + digestOf([]byte("recent"))
if err := k.vals.Put(recent, "cmVjZW50"); err != nil {
t.Fatal(err)
}
if err := k.sweep(); err != nil {
t.Fatal(err)
}
if e, _ := k.vals.KV.Get(old); e != nil || len(objs.objs) != 0 {
t.Errorf("the input of the old form is kept (%v) with %d objects", e, len(objs.objs))
}
if e, _ := k.vals.KV.Get(recent); e == nil {
t.Error("an input of the old form under a day old was deleted early")
}
// a new content the cap refuses says the fill; the same content, already kept, needs no room
full := newTestKeeperWithFill(objs, now, inputsCap-10)
if _, err := full.keep("ask-8", []byte("fits")); err != nil {
@@ -125,7 +125,6 @@ const (
StateDifferences = "differences"
StateCompositions = "compositions"
StateAssignmentRevisions = "assignment-revisions"
StateInputs = "inputs"
)
// WantsByWantNodeModuleKey is the key of one value of the state wants under the form "want.<node>.<module>".
@@ -741,37 +740,6 @@ func DecodeAssignmentRevisionsByEntryDigestValue(raw []byte) (AssignmentRevision
return v, nil
}
// InputsByDigestKey is the key of one value of the state inputs under the form "<digest>".
func InputsByDigestKey(digest string) string { return digest }
// ParseInputsByDigestKey reads the parts of a key of the form "<digest>", in the order of the form; the last result is false for a key of another form.
func ParseInputsByDigestKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodeInputsByDigestValue reads one value of the state inputs under the form "<digest>", refusing a field InputsByDigestValue does not know and any text after the value.
func DecodeInputsByDigestValue(raw []byte) (InputsByDigestValue, error) {
var v InputsByDigestValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// Ask is an ask the assigner puts to a person: the router's ask whole, as the assigner composes it, and how many times it was written at its key.
type Ask struct {
// the seat operator-channel's ask, whole
@@ -1350,6 +1318,3 @@ type AssignmentRevisionsByCandidateGroupHeadsValue = AssignmentRevision
// AssignmentRevisionsByEntryDigestValue is one value of the state assignment-revisions under the key entry.<digest>.
type AssignmentRevisionsByEntryDigestValue = AssignmentEntry
// InputsByDigestValue is one value of the state inputs under the key <digest>.
type InputsByDigestValue = string
@@ -808,22 +808,6 @@
"description": "an entry, written once, removed when no kept revision lists it"
}
]
},
{
"name": "inputs",
"template": "state",
"history": 1,
"description": "a step's input, named by its sha256 alone, kept once per content; a value over one chunk is held in the state's objects store (design 47 G sections 354, 712)",
"key-forms": [
{
"key": "<digest>",
"value": {
"type": "string",
"description": "the input's bytes, base64"
},
"description": "one input"
}
]
}
],
"defs": {
@@ -78,7 +78,6 @@ export declare const states: {
readonly differences: "differences";
readonly compositions: "compositions";
readonly assignmentRevisions: "assignment-revisions";
readonly inputs: "inputs";
};
/** The key of one value of the state wants under the form "want.<node>.<module>". */
@@ -171,12 +170,6 @@ export declare function assignmentRevisionsByEntryDigestKey(digest: string): str
/** The parts of a key of the form "entry.<digest>", or undefined for a key of another form. */
export declare function parseAssignmentRevisionsByEntryDigestKey(_key: string): { digest: string } | undefined;
/** The key of one value of the state inputs under the form "<digest>". */
export declare function inputsByDigestKey(digest: string): string;
/** The parts of a key of the form "<digest>", or undefined for a key of another form. */
export declare function parseInputsByDigestKey(_key: string): { digest: string } | undefined;
/** an ask the assigner puts to a person: the router's ask whole, as the assigner composes it, and how many times it was written at its key */
export interface Ask {
/** the seat operator-channel's ask, whole */
@@ -692,6 +685,3 @@ export type AssignmentRevisionsByCandidateGroupHeadsValue = AssignmentRevision;
/** is one value of the state assignment-revisions under the key entry.<digest>. */
export type AssignmentRevisionsByEntryDigestValue = AssignmentEntry;
/** is one value of the state inputs under the key <digest>. */
export type InputsByDigestValue = string;
@@ -84,7 +84,6 @@ export const states = {
differences: "differences",
compositions: "compositions",
assignmentRevisions: "assignment-revisions",
inputs: "inputs",
};
/** The key of one value of the state wants under the form "want.<node>.<module>". */
@@ -403,18 +402,3 @@ export function parseAssignmentRevisionsByEntryDigestKey(_key) {
return { digest };
}
/** The key of one value of the state inputs under the form "<digest>". */
export function inputsByDigestKey(digest) {
return digest;
}
/** The parts of a key of the form "<digest>", or undefined for a key of another form. */
export function parseInputsByDigestKey(_key) {
let _rest = _key;
if (_rest === "") return undefined;
const digest = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { digest };
}