Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cmd/buildingblock/trigger_run.go
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ With --` + waitFlagName + `, the command waits until the run has ended. This is
accepted = *answer.Status
}
if wait {
return awaitRunEnd(ctx, cmd.OutOrStdout(), output.Format, meshStack.Raw, buildingBlockUuid, accepted)
return awaitRunEnd(ctx, cmd.OutOrStdout(), output.Format, meshStack.Raw, buildingBlockUuid, &accepted)
}
runWait := buildingblock.NewRunWait(meshStack.Raw, buildingBlockUuid)
reacted, block, err := runWait.AwaitReaction(ctx, accepted)
Expand Down
30 changes: 18 additions & 12 deletions cmd/buildingblock/wait.go
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,27 @@ func newWait() *cobra.Command {
)

cmd := &cobra.Command{
Use: "wait <building-block-uuid> --before <file|->",
Use: "wait <building-block-uuid> [--before <file|->]",
Short: "Wait until the run of a building block has ended",
Long: `Wait until meshStack has reacted to a write of a building block, and until the run that the write started has ended. Give the building block by its uuid.
Long: `Wait until the run of a building block has ended. Give the building block by its uuid.

meshStack responds to a write before it starts the run. So right after the write, the building block still shows the action of the previous run. Pass that response with --` + beforeFlagName + `: the response of a create (POST), an update (PUT) or a trigger-run, or a read taken before the change. The command first waits up to a minute until meshStack has reacted, following the rules of https://docs.meshcloud.io/concepts/building-block/#waiting-for-a-run. Then it waits until the run has ended. Press Ctrl-C to stop waiting.
Without --` + beforeFlagName + `, the command waits for the run that is going on now, such as a run that someone started or approved. If no run is going on, the command prints the building block at once.

The command prints the building block. It fails and names the action if the run failed, was aborted or could not start, or if the run is waiting for a person or a dependency.`,
Example: ` meshstack api -X PUT /api/meshobjects/meshbuildingblocks/0b5c1d3e-5f1a-4c2b-9d7e-2a6f8e4b1c90 --request-json block.json |
After a write of the building block, pass meshStack's response to the write with --` + beforeFlagName + `. meshStack responds to a write before it starts the run, so right after the write, the building block still shows the action of the previous run. The response can be that of a create (POST), an update (PUT) or a trigger-run, or a read taken before the change. The command first waits up to a minute until meshStack has reacted, following the rules of https://docs.meshcloud.io/concepts/building-block/#waiting-for-a-run, and then until the run has ended.

Press Ctrl-C to stop waiting. The command prints the building block. It fails and names the action if the run failed, was aborted or could not start, or if the run is waiting for a person or a dependency.`,
Example: ` meshstack bb wait 0b5c1d3e-5f1a-4c2b-9d7e-2a6f8e4b1c90
meshstack api -X PUT /api/meshobjects/meshbuildingblocks/0b5c1d3e-5f1a-4c2b-9d7e-2a6f8e4b1c90 --request-json block.json |
meshstack bb wait 0b5c1d3e-5f1a-4c2b-9d7e-2a6f8e4b1c90 --before=-`,
Args: internal.UuidArg(&buildingBlockUuid),
RunE: func(cmd *cobra.Command, _ []string) error {
before, err := readBefore(cmd, beforeInput, buildingBlockUuid)
if err != nil {
return err
var before *client.MeshBuildingBlockV2Status
if cmd.Flags().Changed(beforeFlagName) {
read, err := readBefore(cmd, beforeInput, buildingBlockUuid)
if err != nil {
return err
}
before = &read
}
meshStack, err := internal.ResolveClient(cmd.Context())
if err != nil {
Expand All @@ -47,7 +54,6 @@ The command prints the building block. It fails and names the action if the run

output.RegisterForItem(cmd.Flags())
beforeInput.Register(cmd.Flags(), beforeFlagName, "file with the building block from before the write, or - to read it from stdin")
_ = cmd.MarkFlagRequired(beforeFlagName)

return cmd
}
Expand All @@ -70,8 +76,8 @@ func readBefore(cmd *cobra.Command, input internal.JsonInputFlag[client.MeshBuil
}

// awaitRunEnd writes the building block once its run has ended, and fails on an outcome someone has
// to act on.
func awaitRunEnd(ctx context.Context, out io.Writer, format internal.OutputFormat, raw *client.RawClient, buildingBlockUuid uuid.UUID, before client.MeshBuildingBlockV2Status) error {
// to act on. A nil before waits for the run going on now.
func awaitRunEnd(ctx context.Context, out io.Writer, format internal.OutputFormat, raw *client.RawClient, buildingBlockUuid uuid.UUID, before *client.MeshBuildingBlockV2Status) error {
wait := buildingblock.NewRunWait(raw, buildingBlockUuid)
ended, block, err := wait.AwaitEnd(ctx, before)
if err != nil {
Expand All @@ -80,7 +86,7 @@ func awaitRunEnd(ctx context.Context, out io.Writer, format internal.OutputForma
if err = format.WriteItem(out, ended); err != nil {
return err
}
if err = wait.Outcome(block); err != nil {
if err = wait.Outcome(ctx, block); err != nil {
return err
}
slog.InfoContext(ctx, fmt.Sprintf("The run of building block %s ended with action %s.", buildingBlockUuid, block.Status.Action))
Expand Down
29 changes: 24 additions & 5 deletions cmd/buildingblock/wait_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,11 @@ import (
"github.com/meshcloud/meshstack-cli/internal/testutil/testlogin"
)

const waitedBuildingBlock = "b1d2c3e4-0000-4000-8000-000000000002"
const (
waitedBuildingBlock = "b1d2c3e4-0000-4000-8000-000000000002"
waitingChild = "b1d2c3e4-0000-4000-8000-000000000003"
failedRun = "a0000000-0000-4000-8000-000000000009"
)

func buildingBlockWithRun(action, latestRunUuid string) string {
return fmt.Sprintf(`{"metadata": {"uuid": %q}, "spec": {}, "status": {"action": %q, "latestRunUuid": %q}, `+
Expand All @@ -29,9 +33,16 @@ func TestWaitFailsOnAnOutcomeThatNeedsSomeoneToAct(t *testing.T) {
before := buildingBlockWithRun("NO_ACTION", "run-1")
var current atomic.Pointer[string]
meshStack := fakemeshstack.Start(t, fakemeshstack.Options{})
meshStack.Route("GET /api/meshobjects/meshbuildingblocks/{uuid}", func(w gohttp.ResponseWriter, _ *gohttp.Request) {
meshStack.Route("GET /api/meshobjects/meshbuildingblocks/{uuid}", func(w gohttp.ResponseWriter, r *gohttp.Request) {
if strings.HasSuffix(r.URL.Path, waitingChild) {
_, _ = fmt.Fprintf(w, `{"metadata": {"uuid": %q}, "spec": {}, "status": {"action": "APPROVE_RUN", "latestRunUuid": "child-run"}}`, waitingChild)
return
}
_, _ = io.WriteString(w, *current.Load())
})
meshStack.Route("GET /api/meshobjects/meshbuildingblockruns/"+failedRun+"/logs", func(w gohttp.ResponseWriter, _ *gohttp.Request) {
_, _ = fmt.Fprintf(w, `{"steps": [{"displayName": "Apply", "status": "FAILED", "systemMessage": "Building block %s is IN_PROGRESS, not SUCCEEDED."}]}`, waitingChild)
})
testlogin.LoggedInTo(t, meshStack.URL)

run := func(stdin string, args ...string) (string, error) {
Expand All @@ -44,9 +55,11 @@ func TestWaitFailsOnAnOutcomeThatNeedsSomeoneToAct(t *testing.T) {
return stdout.String(), err
}

t.Run("wait needs the building block from before the write", func(t *testing.T) {
_, err := run("", "wait", waitedBuildingBlock)
require.ErrorContains(t, err, `required flag(s) "before" not set`)
t.Run("without --before, wait prints the building block whose run has ended", func(t *testing.T) {
current.Store(new(buildingBlockWithRun("NO_ACTION", "run-1")))
stdout, err := run("", "wait", waitedBuildingBlock)
require.NoError(t, err)
assert.Contains(t, stdout, `"action": "NO_ACTION"`)
})

t.Run("a failed run fails the wait with its action and the meshPanel link", func(t *testing.T) {
Expand All @@ -57,6 +70,12 @@ func TestWaitFailsOnAnOutcomeThatNeedsSomeoneToAct(t *testing.T) {
assert.Contains(t, stdout, `"action": "REVIEW_ERRORS"`, "the building block still goes to stdout")
})

t.Run("a failed run names the building blocks in its logs that wait for approval", func(t *testing.T) {
current.Store(new(buildingBlockWithRun("REVIEW_ERRORS", failedRun)))
_, err := run(before, "wait", waitedBuildingBlock, "--before=-")
require.ErrorContains(t, err, "building block "+waitingChild+" waits for approval: review its plan with 'meshstack buildingblockrun plan child-run'")
})

t.Run("a run that waits for approval fails the wait and names the waiting and the detect run", func(t *testing.T) {
current.Store(new(strings.Replace(buildingBlockWithRun("APPROVE_RUN", "run-2"), `"latestRunUuid"`, `"latestDryRunUuid": "run-1", "latestRunUuid"`, 1)))
_, err := run(before, "wait", waitedBuildingBlock, "--before=-")
Expand Down
61 changes: 54 additions & 7 deletions cmd/internal/buildingblock/run_wait.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ import (
"encoding/json/jsontext"
"encoding/json/v2"
"fmt"
"regexp"
"slices"
"strings"
"time"
"uuid"

Expand Down Expand Up @@ -46,11 +49,13 @@ func (w RunWait) AwaitReaction(ctx context.Context, before client.MeshBuildingBl
return reacted, block, withMeshPanelLink(err, block)
}

// AwaitEnd returns the building block once meshStack has reacted to a write since before, and the run
// is no longer running.
func (w RunWait) AwaitEnd(ctx context.Context, before client.MeshBuildingBlockV2Status) (jsontext.Value, *client.MeshBuildingBlockV2, error) {
if _, _, err := w.AwaitReaction(ctx, before); err != nil {
return nil, nil, err
// AwaitEnd returns the building block once its run is no longer running. Given a before, it first
// waits until meshStack has reacted to a write since before; a nil before is the run going on now.
func (w RunWait) AwaitEnd(ctx context.Context, before *client.MeshBuildingBlockV2Status) (jsontext.Value, *client.MeshBuildingBlockV2, error) {
if before != nil {
if _, _, err := w.AwaitReaction(ctx, *before); err != nil {
return nil, nil, err
}
}
ended, block, err := w.poll(ctx, w.endEvery, func(block *client.MeshBuildingBlockV2) (bool, error) {
return block.RunEndedSince(client.MeshBuildingBlockV2Status{})
Expand All @@ -66,14 +71,14 @@ func (w RunWait) StartFailure(block *client.MeshBuildingBlockV2) error {
}

// Outcome is an error for a run that ended in a state someone has to act on.
func (w RunWait) Outcome(block *client.MeshBuildingBlockV2) error {
func (w RunWait) Outcome(ctx context.Context, block *client.MeshBuildingBlockV2) error {
status := block.Status
var err error
switch {
case status.RunStartFailure != "":
return w.StartFailure(block)
case status.RunFailed():
err = fmt.Errorf("the run of building block %s ended with action %s", w.buildingBlockUuid, status.Action)
err = fmt.Errorf("the run of building block %s ended with action %s%s", w.buildingBlockUuid, status.Action, w.waitingBlocks(ctx, status.GetLatestRunUuid()))
case status.Action == client.BuildingBlockActionApproveRun:
err = fmt.Errorf("run %s of building block %s is waiting for approval of the plan from the detect run %s. Review the plan with 'meshstack buildingblockrun plan %s'",
status.GetLatestRunUuid(), w.buildingBlockUuid, status.GetLatestDryRunUuid(), status.GetLatestRunUuid())
Expand All @@ -83,6 +88,48 @@ func (w RunWait) Outcome(block *client.MeshBuildingBlockV2) error {
return withMeshPanelLink(err, block)
}

// maxMentionedBlocks bounds the reads of waitingBlocks, which reads every uuid in the logs.
const maxMentionedBlocks = 20

var uuidPattern = regexp.MustCompile(`[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`)

// waitingBlocks names the building blocks that the logs of a failed run mention and that wait for
// someone. A run that writes building blocks, such as a starterkit, fails when one of them waits for
// an approval, and only the run's messages name that building block.
func (w RunWait) waitingBlocks(ctx context.Context, runUuid string) string {
run, err := uuid.Parse(runUuid)
if err != nil {
return ""
}
logs, err := w.raw.Get[client.MeshBuildingBlockRun](ctx, run, "logs")
if err != nil {
return ""
}
var mentioned, waiting []string
for _, found := range uuidPattern.FindAllString(string(logs), -1) {
if found == w.buildingBlockUuid.String() || slices.Contains(mentioned, found) || len(mentioned) == maxMentionedBlocks {
continue
}
mentioned = append(mentioned, found)
read, err := w.raw.Get[client.MeshBuildingBlockV2](ctx, uuid.MustParse(found))
var block client.MeshBuildingBlockV2
if err != nil || json.Unmarshal(read, &block) != nil || !block.IsWaitingForInput() {
continue
}
if block.Status.Action == client.BuildingBlockActionApproveRun {
waiting = append(waiting, fmt.Sprintf("building block %s waits for approval: review its plan with 'meshstack buildingblockrun plan %s'",
found, block.Status.GetLatestRunUuid()))
} else {
waiting = append(waiting, fmt.Sprintf("building block %s waits with action %s", found, block.Status.Action))
}
}
if len(waiting) == 0 {
return ""
}
return fmt.Sprintf(". The logs of the run name building blocks that wait for someone: %s. Act on them, and then run building block %s again",
strings.Join(waiting, "; "), w.buildingBlockUuid)
}

func withMeshPanelLink(err error, block *client.MeshBuildingBlockV2) error {
if link := block.MeshPanelLink(); err != nil && link != "" {
return fmt.Errorf("%w. Open it in meshPanel: %s", err, link)
Expand Down
15 changes: 12 additions & 3 deletions skills/meshstack-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ skill and the help disagree, trust the help.
| `meshstack workspace list` | | workspaces this login can see |
| `meshstack buildingblock list` | `bb` | building blocks (deployed instances), newest first |
| `meshstack buildingblock trigger-run <uuid>` | `bb` | starts a run of one block |
| `meshstack buildingblock wait <uuid> --before <file\|->` | `bb` | waits until the run of one block has ended |
| `meshstack buildingblock wait <uuid> [--before <file\|->]` | `bb` | waits until the run of one block has ended |
| `meshstack buildingblock tfstate` | `bb` | reads and writes the OpenTofu state of one block |
| `meshstack buildingblockdefinition list` | `bbd` | definitions — what platform teams offer |
| `meshstack buildingblockdefinitionversion list --definition <uuid>` | `bbdv` | the versions of one definition |
Expand Down Expand Up @@ -380,9 +380,18 @@ meshstack api -X PUT /api/meshobjects/meshbuildingblocks/<uuid> --request-json b
meshstack bb wait <uuid> --before=-
```

Both fail, and name the action, when the run failed or waits for a person or a dependency. When the
To wait for a run that is already going, such as one that an approval started, leave out
`--before`:

```sh
meshstack bb wait <uuid>
```

All of them fail, and name the action, when the run failed or waits for a person or a dependency. When the
run waits for approval, they name the waiting run and the detect run that planned it: see
[Approval gates and preflight runs](#approval-gates-and-preflight-runs).
[Approval gates and preflight runs](#approval-gates-and-preflight-runs). A run that creates building
blocks, such as a starterkit, fails when one of them waits for approval. Then the error names that
building block: approve its run, and run the parent again.

A block that deletes itself at the end of its run, like a starterkit, is gone before `bb wait` can
read the outcome. Poll its runs instead: `meshstack bbrun list --building-block <uuid> --workspace
Expand Down
Loading