mesh-delivery/modules/mesh-delivery-builder/cmd/mesh-delivery-builder-tools/main.go

// Command mesh-delivery-builder-tools serves the builder's tools (novox/hq issue 1945): the runtime launches it for a call.
// builder_stuck reads the builder's builds and reasks states and the build modules' steps through the builder's state and
// reads; builder_ask_again writes one value of the reasks state, which the builder watches and answers. The builder is the
// other program: it serves no tool (ADR 0437 §4).
package main

import (
	"encoding/json"
	"fmt"
	"os"
	"strings"
	"time"

	stdio "git.novox.be/novox/mesh-sdk/go"

	"mesh-delivery-builder/internal/build"
)

// Tools are the builder's two tools: stuck reads, askAgain writes the reasks value.
func Tools(r build.StuckReader, askAgain func(key string, value []byte) error, now func() time.Time) []stdio.Tool {
	str := func(args map[string]any, k string) string { s, _ := args[k].(string); return strings.TrimSpace(s) }
	return []stdio.Tool{
		{Name: build.StuckTool,
			Description: "Every build key that waits (building or queued), oldest first: its module, fingerprint, step words and since when, and each ask it " +
				"waits on by language with its id, when it was put, its asking (1 for the first; the builder asks an ask again when it can no longer be " +
				"answered, at most 3 times) and what its build module's steps hold of it (none, or its state on its node since its start). The " +
				"seat workers' delivery counts are not readable by the builder. With module, that module's keys only. Read-only.",
			Input: map[string]any{"type": "object", "properties": map[string]any{
				"module": map[string]any{"type": "string", "description": "only this module's keys"}}},
			Run: func(args map[string]any) (any, error) { return r.Stuck(str(args, "module")) }},
		{Name: build.AskAgainTool,
			Description: "Ask a waiting build key's asks again now, under new ids the key then names, as the builder does by itself for an ask its build " +
				"seat's stream gave up on. The builder answers in the reasks state, which " + build.StuckTool + " shows beside the key; a key no ask of " +
				"which waits is answered so and nothing is asked. An ask whose step already runs on a node is asked again too: it is then " +
				"built twice, the first run's work wasted and its end read by nobody, never a wrong key; builder_stuck shows whether a step runs.",
			Input: map[string]any{"type": "object", "required": []string{"module", "fp", "why"}, "properties": map[string]any{
				"module": map[string]any{"type": "string", "description": "the module's name"},
				"fp":     map[string]any{"type": "string", "description": "its new-form fingerprint, src2:<hex>, as builder_stuck shows it"},
				"why":    map[string]any{"type": "string", "description": "why it is asked again, in plain words"}}},
			Run: func(args map[string]any) (any, error) {
				key, value, err := build.NewReAsk(str(args, "module"), str(args, "fp"), str(args, "why"), stdio.CallerOf(args), now())
				if err != nil {
					return nil, err
				}
				if err := askAgain(key, value); err != nil {
					return nil, fmt.Errorf("the ask could not be written to %s: %w", build.ReAsksBucket, err)
				}
				return map[string]any{"key": key, "asked": true,
					"next": "the builder answers in " + build.ReAsksState + "." + key + "; " + build.StuckTool + " shows the answer and the new ask"}, nil
			}},
	}
}

func read(s stdio.KeptState) build.StateRead {
	return build.StateRead{Keys: s.Keys, Get: func(key string) (json.RawMessage, time.Time, error) {
		e, err := s.Get(key)
		if err != nil || e == nil {
			return nil, time.Time{}, err
		}
		return e.Value, written(s, key, e.Revision), nil
	}}
}

// written is when the key's revision was written, from its history, or zero.
func written(s stdio.KeptState, key string, revision uint64) time.Time {
	h, err := s.History(key)
	if err != nil {
		return time.Time{}
	}
	for _, r := range h {
		if r.Revision == revision {
			return r.At
		}
	}
	return time.Time{}
}

func main() {
	steps := map[string]build.StateRead{}
	for _, bm := range build.StuckBuildModules {
		steps[bm] = read(stdio.State(bm + ".steps"))
	}
	reasks := stdio.State(build.ReAsksState)
	r := build.StuckReader{Builds: read(stdio.State("builds")), ReAsks: read(reasks), Steps: steps}
	put := func(key string, value []byte) error {
		_, err := reasks.Put(key, json.RawMessage(value))
		return err
	}
	if err := stdio.Serve("", Tools(r, put, time.Now)); err != nil {
		fmt.Fprintf(os.Stderr, "[mesh-delivery-builder-tools] %v\n", err)
		os.Exit(1)
	}
}