Files
mesh-delivery/modules/mesh-delivery-sdk/steprun/outputs.go
T
jschoubben 2b79ee1593 A missing output is said as missing; a failed build keeps its error (H-A-482)
The verb output failed "holds no header" on an empty object, since the
runtime's object read answers an absent object as empty data without an
error: an empty object is now no object, said "the ask kept no output".
A failed build kept nothing for the verb output to answer: it now keeps
its error text, as the build module bounded it, as the ask's output
object with the header a test step's carries.

Builds: design 47 H2 H-A-482, H-A-482 addendum (a)
2026-11-22 19:14:02 +01:00

177 lines
7.2 KiB
Go

package steprun
import (
"bytes"
"encoding/json"
"errors"
"fmt"
"time"
"unicode/utf8"
sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/catalogue"
)
// OutputsStore is the local name of the object store a build seat's holder keeps a run's output in (design 47 H2 §791,
// §820): its `outputs` objects, which the holder's manifest `requires` with their cap and max-age, and which the seat's verb
// output reads (H-A-399 (1)).
const OutputsStore = "outputs"
// AnswersStore is the local name of the object store a build seat's holder keeps a step's end in when it is over what the
// steps state's value or step-ended carries (design 47 H2 H-A-412 addendum): the steps state's own objects store,
// `steps-objects`, which the holder's manifest `requires` with its steps state, and which the seat's verb answer reads.
var AnswersStore = catalogue.StateObjectsName("steps")
// OutputObjects is an object store as a holder uses it (mesh-sdk busstate.ObjectsOf(OutputsStore), or of AnswersStore).
type OutputObjects interface {
Put(name string, data []byte, description string) (buscalls.ObjectInfo, error)
Get(name string) (buscalls.ObjectData, error)
}
// KeepAnswerIn is a holder's Puller.KeepAnswer over its store of answers (AnswersStore).
func KeepAnswerIn(o OutputObjects) func(object string, body []byte) error {
return func(object string, body []byte) error {
if o == nil {
return fmt.Errorf("this module keeps no %s store", AnswersStore)
}
_, err := o.Put(object, body, "a step's end over what its key or step-ended carries, named by it")
return err
}
}
// ReadAnswerFrom is a holder's read of a kept end for AnswerTool over its store of answers (AnswersStore).
func ReadAnswerFrom(o OutputObjects) func(object string) ([]byte, error) {
return func(object string) ([]byte, error) {
if o == nil {
return nil, fmt.Errorf("this module keeps no %s store", AnswersStore)
}
got, err := o.Get(object)
if err != nil {
return nil, fmt.Errorf("the answer %s in the %s store: %w", object, AnswersStore, err)
}
return got.Data, nil
}
}
// OutputsMaxAge is the outputs objects' max-age (design 47 H2 §820: 7 days), past which the bus removes a run's output and
// the verb output answers it no longer kept.
const OutputsMaxAge = 7 * 24 * time.Hour
// OutputTail is how much of a run's output the verb output answers: its last 64 KB (design 47 H2 §791).
const OutputTail = 64 << 10
// outputHeader is the header a run's output object holds beside its text (design 47 H2 H-A-412 (1)): the text's size and the
// failing tests with their words taken from the level's results, so the verb output answers them without reading the text
// again. The object is the header's JSON on its first line, then the text.
type outputHeader struct {
Size int `json:"size"`
Failing []sdkstep.FailingTest `json:"failing,omitempty"`
}
// keepOutput writes a run's test output as the object `<node>.<ask id>` in the outputs objects (design 47 H2 §791,
// H-A-412): the header of its size and failing tests, then the text.
func keepOutput(o OutputObjects, node, ask, text string, failing []sdkstep.FailingTest) error {
if o == nil {
return fmt.Errorf("this module keeps no %s store", OutputsStore)
}
name, err := sdkstep.StepKey(node, ask)
if err != nil {
return err
}
head, err := json.Marshal(outputHeader{Size: len(text), Failing: failing})
if err != nil {
return err
}
_, err = o.Put(name, append(append(head, '\n'), text...), "a run's test output, named by its step key")
return err
}
// EndedHere is the verb output's read of this node's steps state (design 47 H2 H-A-412 second addendum (b)): whether a key
// of keys holds the ask's step on node, and when it ended (zero while it runs). keys and get read the holder's steps state.
func EndedHere(node string, keys func() ([]string, error), get func(key string) (json.RawMessage, error)) func(ask string) (time.Time, bool, error) {
return func(ask string) (time.Time, bool, error) {
if keys == nil || get == nil {
return time.Time{}, false, errors.New("this module reads no steps state")
}
all, err := keys()
if err != nil {
return time.Time{}, false, fmt.Errorf("the steps state's keys: %w", err)
}
for _, k := range all {
if _, n, id, perr := sdkstep.ParseStepKey(k); perr != nil || n != node || id != ask {
continue
}
raw, err := get(k)
if err != nil {
return time.Time{}, false, fmt.Errorf("the step key %s: %w", k, err)
}
if raw == nil {
continue
}
step, err := sdkstep.DecodeStep(raw)
if err != nil {
return time.Time{}, false, fmt.Errorf("the step key %s: %w", k, err)
}
if !sdkstep.Ended(step) {
return time.Time{}, true, nil
}
return step.Ended, true, nil
}
return time.Time{}, false, nil
}
}
// readOutput answers the verb output for ask (design 47 H2 §791, H-A-412): from the object `<node>.<ask>`, the text's last
// OutputTail bytes, its size and failing tests from the header; with no object, no longer kept when this node's steps key
// shows the ask ended here more than OutputsMaxAge ago, and refused otherwise, naming why (an ask never run here, or one
// that kept no output). An empty object is no object (H-A-482): the runtime's object read answers an absent object as
// empty data without an error, which is not a header fault.
func readOutput(o OutputObjects, node, ask string, ended func(ask string) (time.Time, bool, error)) (sdkstep.OutputAnswer, error) {
if o == nil {
return sdkstep.OutputAnswer{}, fmt.Errorf("this module keeps no %s store", OutputsStore)
}
name, err := sdkstep.StepKey(node, ask)
if err != nil {
return sdkstep.OutputAnswer{}, err
}
got, gerr := o.Get(name)
if gerr == nil && len(got.Data) > 0 {
return outputOf(ask, got.Data)
}
if gerr == nil {
gerr = fmt.Errorf("the object %s in the %s store is empty", name, OutputsStore)
}
if ended == nil {
return sdkstep.OutputAnswer{}, fmt.Errorf("the ask %s kept no output: %w", ask, gerr)
}
at, here, err := ended(ask)
switch {
case err != nil:
return sdkstep.OutputAnswer{}, fmt.Errorf("the output %s is not in the %s store (%v), and this node's steps state cannot say why: %w", name, OutputsStore, gerr, err)
case !here:
return sdkstep.OutputAnswer{}, fmt.Errorf("the ask %s never ran on %s: no step key of it here", ask, node)
case !at.IsZero() && now().Sub(at) > OutputsMaxAge:
return sdkstep.OutputAnswer{Ask: ask, NoLongerKept: true}, nil
default:
return sdkstep.OutputAnswer{}, fmt.Errorf("the ask %s ran on %s, and the ask kept no output: %w", ask, node, gerr)
}
}
// outputOf is the verb output's answer from an output object's bytes: its header and the text's last OutputTail bytes,
// cut at a whole character.
func outputOf(ask string, data []byte) (sdkstep.OutputAnswer, error) {
line, text, ok := bytes.Cut(data, []byte{'\n'})
var h outputHeader
if !ok || json.Unmarshal(line, &h) != nil {
return sdkstep.OutputAnswer{}, fmt.Errorf("the output of the ask %s holds no header", ask)
}
if len(text) > OutputTail {
text = text[len(text)-OutputTail:]
for len(text) > 0 && !utf8.RuneStart(text[0]) {
text = text[1:]
}
}
return sdkstep.OutputAnswer{Ask: ask, Output: string(text), Size: h.Size, Failing: h.Failing}, nil
}