progress

type Direction struct {
	// ActiveWord is the state word shown while a stream is actively
	// transferring, e.g. "Downloading" or "Uploading".
	ActiveWord string
	// DoneWord is the state word shown for a stream that finished after
	// Activate was called, e.g. "Download complete" or "Upload complete".
	DoneWord string
	// WaitResource names the resource a waiting stream is blocked on
	// ("DataExport" or "DataImport"), interpolated into the
	// direction-independent "Waiting for %s to be Ready" template.
	WaitResource string
	// PastVerb is the lower-case past-tense verb used in the non-TTY
	// aggregate line, e.g. "downloaded" or "uploaded".
	PastVerb string
}

type Option func(*sinkConfig)

type Sink interface {
	// NewStream registers a named stream with a known total byte count.
	// A total of 0 is allowed when the size is not yet known; call SetTotal later.
	NewStream(name string, total int64) Stream

	// SetVolumeTotal sets M, the total number of volume streams this run will
	// download, for the live "N/M volumes downloaded" counter.
	SetVolumeTotal(n int)

	// Wait blocks until all streams have finished and flushes remaining output.
	Wait()

	// LogWriter returns an io.Writer that is safe to use for log output while
	// the sink is active. For the TTY sink it returns a writer whose writes are
	// coordinated with the mpb renderer, so log lines print cleanly above the
	// live bars instead of corrupting their cursor accounting (which otherwise
	// makes the bar re-print as multiple blocks). For the plain (non-TTY) sink
	// it returns os.Stderr, preserving the existing logging behaviour.
	LogWriter() io.Writer
}

type Stream interface {
	// IncrBy advances the stream's byte counter by n.
	IncrBy(n int)

	// SetTotal updates the stream's expected total byte count.
	SetTotal(total int64)

	// SetCurrent sets the stream's current byte counter to an absolute value.
	// It exists for the pipeline's resume-seed clamp: when a resume seed
	// credited from stale on-disk state (a chunk geometry about to be purged,
	// or a stale sizes sidecar) exceeds the fresh authoritative total — a
	// volume shrunk between runs — downloadBlock/downloadFS call
	// SetCurrent(0) to reset the displayed value to 0 BEFORE lowering the
	// total, so the bar never renders current > total. It is an absolute
	// DOWNWARD correction only; ordinary forward progress is reported with
	// IncrBy, never with SetCurrent.
	SetCurrent(current int64)

	// Activate transitions the stream from waiting to downloading state.
	// For the TTY sink it flips the bar from "waiting for export…" to the live
	// byte-counter display. For the plain (non-TTY) sink it is a no-op.
	// Must be called exactly once after the DataExport becomes ready, before
	// byte transfer begins.
	Activate()

	// Done marks the stream as successfully complete and counts it toward the
	// "N/M volumes downloaded" completion total. If Fail was already called on
	// this stream, Done is a no-op (the first terminal call wins; see Fail).
	Done()

	// Fail marks the stream as terminated WITHOUT completing successfully (the
	// underlying transfer was cancelled or errored, or the stream's DataExport
	// never became ready). Unlike Done, a failed stream is excluded from the
	// "N/M volumes downloaded" / "(N/M volumes)" completion counters, so M (the
	// total) stays correct but a failed stream never counts as one of the N
	// completions. Fail still unblocks Wait() the same way Done does, and may be
	// called from the waiting state (before Activate) or the active state.
	// If Done was already called on this stream, Fail is a no-op (the first
	// terminal call wins; see Done).
	Fail()
}