WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

cli/cmd/doc/wait.go

@@ -0,0 +1,331 @@
+package doc
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"math/rand"
+	"sync"
+	"time"
+
+	sdk "github.com/Tencent/WeKnora/client"
+	"github.com/spf13/cobra"
+
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+)
+
+// WaitOptions captures `doc wait` flag state.
+type WaitOptions struct {
+	IDs      []string
+	Timeout  time.Duration
+	Interval time.Duration
+}
+
+// NewCmdWait builds `weknora doc wait <id> [<id>...]`.
+//
+// Multi-id behaviour is always wait-all: blocks until every id reaches a
+// terminal state. Use shell composition
+// (`weknora doc wait id1 && weknora doc wait id2`) when fail-fast is
+// desired.
+func NewCmdWait(f *cmdutil.Factory) *cobra.Command {
+	opts := &WaitOptions{}
+	cmd := &cobra.Command{
+		Use:   "wait <doc-id> [<doc-id>...]",
+		Short: "Wait for one or more documents to finish parsing",
+		Long: `Block until every given document reaches a terminal parse_status
+(completed or failed), the timeout expires, or the user interrupts (Ctrl-C).
+Always wait-all: every id must reach a terminal state before returning.
+
+Exit codes:
+  0    all completed
+  1    any failed
+  124  --timeout reached (matches GNU 'timeout' command)
+  130  Ctrl-C / SIGINT
+
+Multi-id is polled concurrently (max 5 parallel; use 'xargs -P' for more).
+For fail-fast semantics, use shell composition:
+  weknora doc wait id1 && weknora doc wait id2 && weknora doc wait id3`,
+		Example: `  weknora doc wait doc_abc
+  weknora doc wait id1 id2 id3 --timeout 20m
+  weknora doc wait id1 id2 --format ndjson`,
+		Args: cobra.MinimumNArgs(1),
+		RunE: func(c *cobra.Command, args []string) error {
+			// Validate flags FIRST so an invalid --format doesn't cost the
+			// user a multi-minute poll before erroring out.
+			fopts, err := cmdutil.CheckFormatFlag(c)
+			if err != nil {
+				return err
+			}
+			fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
+
+			opts.IDs = args
+			cli, err := f.Client()
+			if err != nil {
+				return err
+			}
+			res, err := waitForDocs(c.Context(), opts.IDs, cli, *opts)
+			if err != nil {
+				return err
+			}
+
+			if err := emitWaitResult(res, fopts, iostreams.IO.Out); err != nil {
+				return err
+			}
+
+			// The partition (completed/failed/timeout) is already on stdout via
+			// emitWaitResult. On aggregate failure we still need a non-zero exit,
+			// but the error is Silent so PrintError does NOT write a second,
+			// contradictory {ok:false} envelope to stderr — the agent reads the
+			// failure detail from the stdout partition + the exit code (1/124).
+			// Same contract as cmdutil.RunBatch.
+			switch res.ExitCode() {
+			case 0:
+				return nil
+			case 1:
+				return cmdutil.NewError(cmdutil.CodeOperationFailed, fmt.Sprintf("%d doc(s) failed", len(res.Failed))).WithSilent()
+			case 124:
+				return cmdutil.NewError(cmdutil.CodeOperationTimeout, fmt.Sprintf("wait timed out (%d doc(s) still pending)", len(res.Timeout))).WithSilent()
+			}
+			return nil
+		},
+	}
+	cmd.Flags().DurationVar(&opts.Timeout, "timeout", 10*time.Minute, "Max wait time before exiting 124")
+	cmd.Flags().DurationVar(&opts.Interval, "interval", 2*time.Second, "Initial poll interval; exponential backoff capped at 15s + jitter")
+	cmdutil.AddFormatFlag(cmd)
+	cmdutil.AddIgnoredKBFlag(cmd)
+	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
+		UsedFor:       "block until one or more documents reach a terminal parse state (completed or failed), or --timeout elapses",
+		RequiredFlags: []string{"<doc-id>... (one or more positionals)"},
+		Examples: []string{
+			"weknora doc wait doc_abc",
+			"weknora doc wait doc_a doc_b --timeout 5m",
+		},
+		Output: "envelope.data is {completed:[], failed:[{id,message}], timeout:[]}",
+		Warnings: []string{
+			"exit code carries the aggregate result: 0 all completed, 1 any failed, 124 timeout",
+			"ok:true means the wait ran to a terminal state — NOT that every doc succeeded; branch on the exit code or inspect data.failed",
+		},
+	})
+	return cmd
+}
+
+// ---------------------------------------------------------------------------
+// Core poll loop (B2)
+// ---------------------------------------------------------------------------
+
+// WaitService is the narrow SDK surface needed for polling.
+type WaitService interface {
+	GetKnowledge(ctx context.Context, id string) (*sdk.Knowledge, error)
+}
+
+// WaitResult is the terminal-state partition returned by waitForDocs.
+type WaitResult struct {
+	Completed []string    `json:"completed"`
+	Failed    []FailedDoc `json:"failed,omitempty"`
+	Timeout   []string    `json:"timeout,omitempty"`
+}
+
+// FailedDoc carries the id + reason for a doc that reached parse_status=failed
+// or that GetKnowledge returned an error for.
+type FailedDoc struct {
+	ID      string `json:"id"`
+	Code    string `json:"code,omitempty"`
+	Message string `json:"message,omitempty"`
+}
+
+const (
+	maxConcurrentPolls = 5
+	maxBackoffInterval = 15 * time.Second
+	jitterMax          = 500 * time.Millisecond
+)
+
+// waitForDocs polls each id until terminal state or timeout. Concurrency is
+// bounded by maxConcurrentPolls. Returns the partitioned terminal state.
+// Always waits for every id (wait-all semantics).
+//
+// Duplicate ids are deduplicated at entry — polling the same id twice would
+// produce duplicate result entries and waste poll quota.
+//
+// Exponential backoff starts at opts.Interval, doubles each tick, caps at
+// maxBackoffInterval, with up to jitterMax random jitter added per sleep.
+func waitForDocs(ctx context.Context, ids []string, svc WaitService, opts WaitOptions) (*WaitResult, error) {
+	// Dedup ids while preserving first-seen order.
+	seen := make(map[string]struct{}, len(ids))
+	deduped := make([]string, 0, len(ids))
+	for _, id := range ids {
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		deduped = append(deduped, id)
+	}
+	ids = deduped
+
+	ctx, cancel := context.WithTimeout(ctx, opts.Timeout)
+	defer cancel()
+
+	// Completed is non-omitempty (always present in the partition), so start it
+	// as an empty slice rather than nil — agents see `"completed":[]`, not null.
+	result := &WaitResult{Completed: []string{}}
+	var mu sync.Mutex
+	addCompleted := func(id string) {
+		mu.Lock()
+		defer mu.Unlock()
+		result.Completed = append(result.Completed, id)
+	}
+	addFailed := func(fd FailedDoc) {
+		mu.Lock()
+		defer mu.Unlock()
+		result.Failed = append(result.Failed, fd)
+	}
+	addTimeout := func(id string) {
+		mu.Lock()
+		defer mu.Unlock()
+		result.Timeout = append(result.Timeout, id)
+	}
+
+	sem := make(chan struct{}, maxConcurrentPolls)
+	var wg sync.WaitGroup
+	for _, id := range ids {
+		wg.Add(1)
+		go func(id string) {
+			defer wg.Done()
+			sem <- struct{}{}
+			defer func() { <-sem }()
+
+			interval := opts.Interval
+			for {
+				select {
+				case <-ctx.Done():
+					// Distinguish SIGINT/SIGTERM (Canceled) from --timeout
+					// (DeadlineExceeded) so a user interrupt does not
+					// pollute the timeout list with the in-flight ids.
+					if errors.Is(ctx.Err(), context.Canceled) {
+						// Signal-driven cancel: root's signal handler
+						// exits 130; don't classify these ids as timed out.
+						return
+					}
+					addTimeout(id)
+					return
+				default:
+				}
+
+				doc, err := svc.GetKnowledge(ctx, id)
+				if err != nil {
+					// Check Canceled first — SIGINT during an in-flight
+					// request surfaces as a context-canceled error; it is
+					// not a real GetKnowledge failure.
+					if errors.Is(ctx.Err(), context.Canceled) {
+						return
+					}
+					if errors.Is(ctx.Err(), context.DeadlineExceeded) {
+						addTimeout(id)
+						return
+					}
+					addFailed(FailedDoc{ID: id, Message: err.Error()})
+					return
+				}
+
+				switch doc.ParseStatus {
+				case "completed":
+					addCompleted(id)
+					return
+				case "failed":
+					addFailed(FailedDoc{ID: id, Message: doc.ErrorMessage})
+					return
+				case "draft":
+					// draft = created but NOT queued for parsing (inline
+					// `doc create` leaves docs here; file `doc upload`
+					// auto-enqueues). It never progresses on its own, so
+					// waiting would hang to the --timeout (124). Fail fast with
+					// the exact unblock command instead of silently polling.
+					addFailed(FailedDoc{ID: id, Message: "parse_status=draft: not queued for parsing — run `weknora doc reparse " + id + "` to index it"})
+					return
+				}
+
+				// Not yet terminal — sleep with jitter, then exp-backoff.
+				jitter := time.Duration(rand.Int63n(int64(jitterMax)))
+				timer := time.NewTimer(interval + jitter)
+				select {
+				case <-ctx.Done():
+					timer.Stop()
+					if errors.Is(ctx.Err(), context.Canceled) {
+						return
+					}
+					addTimeout(id)
+					return
+				case <-timer.C:
+				}
+				interval *= 2
+				if interval > maxBackoffInterval {
+					interval = maxBackoffInterval
+				}
+			}
+		}(id)
+	}
+	wg.Wait()
+	return result, nil
+}
+
+// ExitCode resolves the compound terminal state to a Unix exit code.
+// Priority: 1 > 124 > 0 (failed > timeout > completed). SIGINT (exit 130)
+// is handled by the Go runtime / context cancellation, not here.
+func (r *WaitResult) ExitCode() int {
+	if len(r.Failed) > 0 {
+		return 1
+	}
+	if len(r.Timeout) > 0 {
+		return 124
+	}
+	return 0
+}
+
+// Compile-time assertion: *sdk.Client satisfies WaitService.
+var _ WaitService = (*sdk.Client)(nil)
+
+// ---------------------------------------------------------------------------
+// B5: output rendering
+// ---------------------------------------------------------------------------
+
+// emitWaitResult renders r according to --format. Output writer is
+// parametrized for tests; production callers pass iostreams.IO.Out.
+func emitWaitResult(r *WaitResult, fopts *cmdutil.FormatOptions, w io.Writer) error {
+	switch fopts.Mode {
+	case cmdutil.FormatJSON, cmdutil.FormatNDJSON:
+		return fopts.Emit(w, r, nil)
+	case cmdutil.FormatText, "":
+		return writeWaitText(w, r)
+	default:
+		return fmt.Errorf("unsupported --format %q for doc wait", fopts.Mode)
+	}
+}
+
+// writeWaitText renders r as human-readable lines:
+//
+//	✓ <id> completed
+//	✗ <id> failed: <message>
+//	⏱ <id> timeout
+func writeWaitText(w io.Writer, r *WaitResult) error {
+	for _, id := range r.Completed {
+		if _, err := fmt.Fprintf(w, "✓ %s completed\n", id); err != nil {
+			return err
+		}
+	}
+	for _, fd := range r.Failed {
+		msg := fd.Message
+		if msg == "" {
+			msg = "(no message)"
+		}
+		if _, err := fmt.Fprintf(w, "✗ %s failed: %s\n", fd.ID, msg); err != nil {
+			return err
+		}
+	}
+	for _, id := range r.Timeout {
+		if _, err := fmt.Fprintf(w, "⏱ %s timeout\n", id); err != nil {
+			return err
+		}
+	}
+	return nil
+}