diff --git a/cmd/buildingblock/trigger_run.go b/cmd/buildingblock/trigger_run.go index bf48d674..5da5f1f5 100644 --- a/cmd/buildingblock/trigger_run.go +++ b/cmd/buildingblock/trigger_run.go @@ -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) diff --git a/cmd/buildingblock/wait.go b/cmd/buildingblock/wait.go index c420e28f..1cef745f 100644 --- a/cmd/buildingblock/wait.go +++ b/cmd/buildingblock/wait.go @@ -22,20 +22,27 @@ func newWait() *cobra.Command { ) cmd := &cobra.Command{ - Use: "wait --before ", + Use: "wait [--before ]", 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 { @@ -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 } @@ -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 { @@ -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)) diff --git a/cmd/buildingblock/wait_test.go b/cmd/buildingblock/wait_test.go index 64de535c..ca418e2e 100644 --- a/cmd/buildingblock/wait_test.go +++ b/cmd/buildingblock/wait_test.go @@ -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}, `+ @@ -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) { @@ -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) { @@ -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=-") diff --git a/cmd/internal/buildingblock/run_wait.go b/cmd/internal/buildingblock/run_wait.go index 3013d63d..fcb8067d 100644 --- a/cmd/internal/buildingblock/run_wait.go +++ b/cmd/internal/buildingblock/run_wait.go @@ -7,6 +7,9 @@ import ( "encoding/json/jsontext" "encoding/json/v2" "fmt" + "regexp" + "slices" + "strings" "time" "uuid" @@ -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{}) @@ -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()) @@ -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) diff --git a/skills/meshstack-cli/SKILL.md b/skills/meshstack-cli/SKILL.md index 9e0363e2..dd9e0721 100644 --- a/skills/meshstack-cli/SKILL.md +++ b/skills/meshstack-cli/SKILL.md @@ -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 ` | `bb` | starts a run of one block | -| `meshstack buildingblock wait --before ` | `bb` | waits until the run of one block has ended | +| `meshstack buildingblock wait [--before ]` | `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 ` | `bbdv` | the versions of one definition | @@ -380,9 +380,18 @@ meshstack api -X PUT /api/meshobjects/meshbuildingblocks/ --request-json b meshstack bb wait --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 +``` + +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 --workspace