// stallguard.go — 一發等不到回覆的請求，不可以讓整台機器的同步停下來
// （`inkstone/arcrun-rag#153`）。
//
// 一輪同步是**一條線**走完的：帳號 → 看守資料夾 → 一件件事。整條線上每一發
// HTTP 都是同步的，所以只要其中一發停在那裡不回來，它後面的所有帳號、所有
// 資料夾就一起停擺——而且是**安靜地**停擺：日誌只有開工那一行，畫面上的
// 資料夾結構永遠停在上一版，沒有任何錯誤訊息。
//
// 為什麼不是「把 300 秒調小」：那只改變**卡多久**，沒改變「一發卡住就全停」。
// 一個階段可以連續打二十發（見 sourcerepair.go 的 sourceRepairBatch），
// 每發都等到超時的話，60 秒的上限一樣會把一輪拖成二十分鐘。
//
// 這支檔把「等待」變成三件有邊界、會說話的事：
//
//	① **每一發自己的上限**——按「這一發實際上在做什麼」給（會同步跑 AI 萃取的
//	   那一發本來就慢，機械收口的那些不該也享有五分鐘），而且用 context 帶進
//	   請求裡，不是只靠 client 那一把套用全部的總閘。
//	② **同一個帳號連續等不到回覆 ⇒ 這一輪不再打它**（斷路器）。一發卡住的代價
//	   從「整輪停擺」降成「這個帳號這一輪跳過」，其他帳號、其他資料夾照常跑完。
//	③ **等待要有話說**——超過 stallNoticeEvery 就往 stdout 播一句
//	   「哪個帳號、哪件事、等了多久」，並在收工時寫進 status.json。
//	   靜默的等待跟當掉對使用者是同一件事。
//
// 🔴 播報用 `phase:"waiting"`，**不能沿用既有的兩種**：supervisor 把任何
// 非 `start` 的 JSON 值都當成「一輪跑完了」（supervisor.go 的 decode 迴圈），
// 沿用會讓托盤在同步途中跳回「看守中」——正是 t191 修掉的那個病。
package collector

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net"
	"os"
	"sync"
	"time"
)

// callStep 描述「這一發網路呼叫在做什麼」。
//
// Name 會出現在日誌與畫面上，所以它是**產品文案**：講使用者認得的那件事，
// 不出現 workflow 名、狀態碼、模型名。
type callStep struct {
	Name   string
	Budget time.Duration
}

// 🔴 **每一個數字都是量出來的，不是推出來的**（2026-08-28 第三輪的教訓）。
//
// 第一輪我用「零 LLM 的機械收口應該很快」這個**推論**給了 60 秒，結果實測分佈是：
//
//	送出一份筆記   33.2 39.9 42.4 43.2 43.3 43.5 43.6 44.2 44.6 44.6
//	              45.5 53.1 53.3 53.6 54.5 54.8 57.3 ← 真實尾巴到 57 秒
//	              60.0 60.0 60.0 ← **這三個是我自己的上限把它剪斷**，不是雲端的耗時
//
// 後果不是「多等一下」：那 2 個被剪斷的檔判成 failed，斷路器跟著跳，
// **後面 9 個檔全部被跳過**，而畫面對使用者說的是「知識庫現在沒有回應」
// ——它一路都在回應，只是慢。**我的推論把一台健康的機器講成壞掉的。**
//
// ⇒ 判準改成：**上限只用來擋「真的不回來」，不用來表達「我認為它該多快」。**
// 每一格都給實測最大值的數倍餘裕；要調它，先去量（`ARCRUN_TRACE=1`）。
const (
	// writeBudget＝任何會把知識寫進雲端的呼叫（收卡／直送萃取／萃取／修出處／下架／收回）。
	// 實測最大 57.3 秒（送出一份筆記）⇒ 300 秒 ≈ 5 倍餘裕。
	// 這也正是改版前 directHTTP 用的數字——事實證明它本來就沒選錯。
	writeBudget = 300 * time.Second
	// registerBudget＝只寫登記簿、不產生知識的呼叫（資料夾總覽／目錄索引／資料夾結構）。
	// 實測 1.8〜26.3 秒 ⇒ 180 秒 ≈ 7 倍餘裕。
	registerBudget = 180 * time.Second
	// probeBudget＝「這台還活著嗎」的唯讀探問。實測 0.0〜1 秒。
	// 它短是因為**它問的就是活著沒**，不是因為我覺得它該多快。
	probeBudget = 20 * time.Second
)

var (
	stepIngestDoc    = callStep{"整理一份文件", writeBudget}
	stepIngestCard   = callStep{"送出一份筆記", writeBudget}
	stepExtractDoc   = callStep{"請雲端讀一份文件", writeBudget}
	stepRepairOrigin = callStep{"更新舊筆記的原文位置", writeBudget}
	stepTakedown     = callStep{"把刪掉的檔案從雲端下架", writeBudget}
	stepRetire       = callStep{"收回這個資料夾在雲端的資料", writeBudget}
	stepFolderTree   = callStep{"回報資料夾結構", registerBudget}
	stepInventory    = callStep{"送出資料夾總覽", registerBudget}
	stepFolderCard   = callStep{"送出目錄索引", registerBudget}
	// stepProbeAI＝每輪每個帳號的第一發（探測雲端 AI 通了沒）。它同時是最早
	// 能認出「這個帳號今天不回應」的位置——認出來，這個帳號其餘的工作就都省了。
	stepProbeAI = callStep{"確認雲端 AI 可不可以用", probeBudget}
	// stepCloudAudit＝跟雲端核對「先前送過的檔案還在不在」。唯讀查詢，
	// 一輪可能連打 cloudAuditBatch 發——正是「一發卡住的代價會被乘上批次大小」的例子。
	stepCloudAudit = callStep{"跟雲端核對哪些檔案還在", probeBudget}
)

// stallNoticeEvery＝等多久開口說一次「還在等」。變數而非常數：測試要把它調快。
var stallNoticeEvery = 30 * time.Second

// stallStrikesBeforeSkip＝同一個帳號連續幾發等到超時，就這一輪不再打它。
//
// 為什麼是 2 而不是 1：一次偶發的逾時不該讓整個帳號這一輪停手。
// 為什麼不是更多：每多一次就是多等一個 Budget，而這正是本票要砍掉的成本。
var stallStrikesBeforeSkip = 2

// StalledCall＝這一輪「等太久」的一件事，寫進 status.json 讓畫面講得出
// 「哪個帳號、哪件事、等了多久」。
type StalledCall struct {
	Account   string `json:"account"`        // 知識庫網址的主機名（使用者在畫面上看得到的那個）
	Step      string `json:"step"`           // 白話的「哪件事」
	WaitedSec int    `json:"waited_sec"`     // 等了幾秒
	Skipped   bool   `json:"skipped"`        // 這一輪之後不再打這個帳號
	Note      string `json:"note,omitempty"` // 給使用者看的一句話
}

// accountStall＝某個帳號在這一輪的「等待帳」。
type accountStall struct {
	strikes int
	answered bool   // 這一輪它**成功回應過** ⇒ 不准說它「沒有回應」
	skip     string // 非空＝這一輪不再打它，內容是給使用者看的理由
}

// roundGuard 一輪一份，掛在 DirectConfig 上。
// makeAccountSubConfig 的 `sub := *c` 會把這個**指標**一起帶過去
// ⇒ 同一輪所有帳號、所有資料夾寫進同一份紀錄，斷路器才跨得了資料夾。
type roundGuard struct {
	mu       sync.Mutex
	accounts map[string]*accountStall
	stalls   []StalledCall
	// announce＝把「還在等」播出去。測試會換掉它（預設寫 stdout）。
	announce func(StalledCall)
}

func newRoundGuard() *roundGuard {
	return &roundGuard{accounts: map[string]*accountStall{}, announce: announceStall}
}

// stdoutMu 保護 stdout 上的「一個 JSON 值」不被另一條 goroutine 插進去切成兩半。
//
// 🔴 為什麼非有不可：播報是在**另一條 goroutine** 上跑的，而每輪結束那筆
// `phase:"done"` 可能有幾十 KB（results 逐筆展開）——超過管線的原子寫入大小之後，
// 兩邊就會交錯。而 supervisor 的 json.Decoder 一旦讀到壞掉的值就
// `io.Copy(io.Discard)` 跳出迴圈（supervisor.go）⇒ **那個行程接下來所有的
// start／done 都不會再被看到**，托盤從此停在錯的狀態。
// 機率很小，代價是整條狀態線靜默死掉——這種比例的東西要用鎖解決，不是賭。
var stdoutMu sync.Mutex

// printJSONLine 把一個值印成 stdout 上完整的一行（與播報共用同一把鎖）。
func printJSONLine(v any) {
	line, err := json.MarshalIndent(v, "", "  ")
	if err != nil {
		return
	}
	stdoutMu.Lock()
	defer stdoutMu.Unlock()
	_, _ = os.Stdout.Write(append(line, '\n'))
}

// announceStall 把一句「還在等」印成 stdout 上的一個 JSON 值。
// 一次寫完整一個值：supervisor 那邊是 json.Decoder 逐值解，寫一半會炸掉整條線。
func announceStall(s StalledCall) {
	line, err := json.Marshal(struct {
		At    string `json:"at"`
		Phase string `json:"phase"`
		StalledCall
	}{time.Now().Format(time.RFC3339), "waiting", s})
	if err != nil {
		return // 播不出去也不能擋住本體
	}
	stdoutMu.Lock()
	defer stdoutMu.Unlock()
	_, _ = os.Stdout.Write(append(line, '\n'))
}

// skipReason 回「這個帳號這一輪已經被判定沒有回應」的白話理由；空＝照常打。
func (g *roundGuard) skipReason(host string) string {
	if g == nil {
		return ""
	}
	g.mu.Lock()
	defer g.mu.Unlock()
	if a := g.accounts[host]; a != nil {
		return a.skip
	}
	return ""
}

// Stalls 回這一輪等太久的清單（順序＝發生順序）。
func (g *roundGuard) Stalls() []StalledCall {
	if g == nil {
		return nil
	}
	g.mu.Lock()
	defer g.mu.Unlock()
	return append([]StalledCall(nil), g.stalls...)
}

// succeeded 記一發「成功回來了」。
//
// 🔴 沒有這個函式的話，`strikes` 只增不減 ⇒ **一輪裡任意兩發逾時就會跳閘**，
// 而訊息上寫的是「**連續** 2 件事都等不到回覆」——那兩個字就是假的。
// 2026-08-28 實撞：一輪成功送出 8 份筆記、中間兩發被我自己過短的上限剪斷，
// 斷路器就跳了，後面 9 個檔全被跳過。
func (g *roundGuard) succeeded(host string) {
	if g == nil {
		return
	}
	g.mu.Lock()
	defer g.mu.Unlock()
	a := g.accounts[host]
	if a == nil {
		a = &accountStall{}
		g.accounts[host] = a
	}
	a.answered = true
	if a.skip == "" {
		a.strikes = 0 // 已經跳閘就不再回頭；沒跳閘的話，成功一次就重新計數
	}
}

// strike 記一發「等到超時」，必要時讓這個帳號這一輪停手。回傳給使用者看的那句話。
func (g *roundGuard) strike(host string, step callStep, waited time.Duration) string {
	g.mu.Lock()
	a := g.accounts[host]
	if a == nil {
		a = &accountStall{}
		g.accounts[host] = a
	}
	a.strikes++
	// 🔴 **它這一輪回應過的話，就不准說它「沒有回應」。**
	// 2026-08-28 實撞：youlin 一路都在回應（成功送出 8 份筆記），只是慢，
	// 而畫面對使用者說「知識庫現在沒有回應」——那是把一台健康的機器講成壞掉的。
	// 使用者會照著這句話去查網路、去重裝，全都白費。
	how := "沒有回應"
	if a.answered {
		how = "回得太慢"
	}
	tripped := a.strikes >= stallStrikesBeforeSkip && a.skip == ""
	if tripped {
		a.skip = fmt.Sprintf(
			"知識庫「%s」現在%s（連續 %d 件事都等不到回覆），這一輪先跳過它；"+
				"其他資料夾照常同步，稍後會自動恢復。",
			host, how, a.strikes)
	}
	// 🔴 結尾那句「稍後會自動恢復」不是修辭，它是 explainsWhySkipped 認得的識別字
	// （sync_status.go）。少了它，這些被跳過的檔會**連一句原因都沒有地從畫面消失**。
	// 有測試守著（TestSkipMessagesAlwaysExplainThemselves），改措辭前先看那條。
	note := fmt.Sprintf("「%s」等了 %d 秒，知識庫「%s」%s；這一輪先跳過，"+
		"其他資料夾照常同步，稍後會自動恢復。",
		step.Name, int(waited.Seconds()), host, how)
	g.stalls = append(g.stalls, StalledCall{
		Account: host, Step: step.Name, WaitedSec: int(waited.Seconds()),
		Skipped: tripped, Note: note,
	})
	announce, skip := g.announce, a.skip
	g.mu.Unlock()

	if announce != nil {
		announce(StalledCall{Account: host, Step: step.Name,
			WaitedSec: int(waited.Seconds()), Skipped: tripped, Note: note})
	}
	// 🔴 把連線池裡那條可能已經死掉的連線丟掉。
	// 實撞的形狀（2026-08-28）：行程活著、CPU 0%、`lsof` 一條 TCP 都沒有，
	// 而堆疊停在 HTTP/2 的 roundTrip——連線在作業系統那層已經沒了，
	// 連線池裡的殼卻還在，後面每一發都會被指派到同一個殼上、一發一發地等到超時。
	// 丟掉之後下一發會重新建立連線，而不是繼續排在一條死掉的連線後面。
	directHTTP.CloseIdleConnections()

	if skip != "" {
		return skip
	}
	return note
}

// unreachableNote 回「這個帳號這一輪已經被判定沒有回應」的白話理由；空＝照常打。
//
// 呼叫端用它在**打之前**就掉頭，而不是打下去等到超時再說——那正是「一發卡住
// 就整輪停擺」的成本來源：不掉頭的話，一個沒有回應的帳號會讓這一輪的每一件事
// 各自再等一個 Budget。
func (c *DirectConfig) unreachableNote() string {
	return c.guard.skipReason(instanceHostOf(c.CypherURL))
}

// callGate＝一發網路呼叫的閘。用法（三行，缺一不可）：
//
//	gate := cfg.openGate(stepXxx)
//	defer gate.release()                     // 停掉播報、放掉 context
//	if note := gate.blocked(); note != "" { … 這一輪不再打這個帳號 … }
//	… 真的去打 …
//	if err != nil { return gate.record(err) } // 逾時才會被記帳，其餘原樣回
type callGate struct {
	g       *roundGuard
	host    string
	step    callStep
	started time.Time
	ctx     context.Context
	cancel  context.CancelFunc
	stop    chan struct{}
	once    sync.Once
	skip    string
	// notice＝多久播報一次。**在 openGate 就抄成自己的一份**，播報那條 goroutine
	// 不再去讀套件層的變數——那條 goroutine 的生命週期比呼叫端長一點點，
	// 讀共用變數就是一個真的資料競爭（-race 抓到的）。
	notice time.Duration
}

// openGate 開一發呼叫的閘。guard 為 nil（測試直接呼叫低層函式）時仍回一個可用的
// 閘：有 context deadline、不記帳、不播報——「沒裝 guard」不該變成「沒有上限」。
func (c *DirectConfig) openGate(step callStep) *callGate {
	host := instanceHostOf(c.CypherURL)
	gate := &callGate{g: c.guard, host: host, step: step, started: time.Now(),
		stop: make(chan struct{}), notice: stallNoticeEvery}
	if c.guard != nil {
		gate.skip = c.guard.skipReason(host)
	}
	gate.ctx, gate.cancel = context.WithTimeout(context.Background(), step.Budget)
	if gate.skip != "" {
		return gate // 已經跳閘：不必播報，呼叫端會立刻回頭
	}
	go gate.keepTalking()
	return gate
}

// keepTalking 在等待期間每隔 stallNoticeEvery 播一句「還在等」。
// 這是本票驗收條件②：卡住的那一發要有話說，而不是靜默。
func (gate *callGate) keepTalking() {
	if gate.g == nil {
		return
	}
	t := time.NewTicker(gate.notice)
	defer t.Stop()
	for {
		select {
		case <-gate.stop:
			return
		case now := <-t.C:
			waited := int(now.Sub(gate.started).Seconds())
			gate.g.mu.Lock()
			announce := gate.g.announce
			gate.g.mu.Unlock()
			if announce != nil {
				announce(StalledCall{
					Account: gate.host, Step: gate.step.Name, WaitedSec: waited,
					Note: fmt.Sprintf("還在等知識庫「%s」回覆「%s」，已經等了 %d 秒。",
						gate.host, gate.step.Name, waited),
				})
			}
		}
	}
}

// blocked 回「這一輪已經不打這個帳號了」的理由；空＝可以打。
func (gate *callGate) blocked() string { return gate.skip }

// traceCalls＝把每一發的「哪件事／打誰／花了多久」印到 stderr（`ARCRUN_TRACE=1` 開）。
//
// 🔴 為什麼要留這個：2026-08-28 第一次修完之後，端到端症狀還在，而現場能拿到的只有
// 一張 SIGQUIT 堆疊——堆疊只說得出「此刻卡在哪一發」，**說不出「這一輪的時間花到哪去了」**。
// 兩個人為此各自推測了一輪。有這一行就不必推測：跑一次，時間分佈直接列出來。
var traceCalls = os.Getenv("ARCRUN_TRACE") != ""

func (gate *callGate) trace(outcome string) {
	if !traceCalls {
		return
	}
	fmt.Fprintf(os.Stderr, "[trace] %7.1fs  %-22s %-8s %s\n",
		time.Since(gate.started).Seconds(), gate.step.Name, outcome, gate.host)
}

// release 停掉播報並放掉 context。**一定要 defer**：context 活到呼叫端讀完回應
// 之後才釋放，所以不能在讀 body 之前呼叫。
func (gate *callGate) release() {
	gate.once.Do(func() { close(gate.stop); gate.trace("done") })
	gate.cancel()
}

// ok 記一發成功（見 roundGuard.succeeded）。與 record 成對，兩者呼叫端都要顧到。
func (gate *callGate) ok() { gate.g.succeeded(gate.host) }

// record 記一發失敗。只有「等到超時」才進帳（連線被拒之類的錯是**很快**回來的，
// 不是本票要修的病，記進去只會讓正常的斷網把帳號誤判成沒有回應）。
// 回傳要交給呼叫端的錯誤：逾時換成白話，其餘原樣。
//
// 可以在 release 之後呼叫——它不碰 context。
func (gate *callGate) record(err error) error {
	if err == nil || !isStallError(err) {
		return err
	}
	waited := time.Since(gate.started)
	if gate.g == nil {
		return fmt.Errorf("「%s」等了 %d 秒，知識庫「%s」沒有回應；稍後會自動恢復。",
			gate.step.Name, int(waited.Seconds()), gate.host)
	}
	return errors.New(gate.g.strike(gate.host, gate.step, waited))
}

// isStallError 回答「這個錯誤是**等到超時**嗎」。
//
// 三種都要認得：我們自己的 context deadline、client.Timeout 包出來的
// `*url.Error{Timeout:true}`、以及被 `%w` 包過好幾層之後的同一個東西
//（萃取那條路會加上「連不上你的知識庫：」再包一層）。
func isStallError(err error) bool {
	if err == nil {
		return false
	}
	if errors.Is(err, context.DeadlineExceeded) {
		return true
	}
	var ne net.Error
	if errors.As(err, &ne) && ne.Timeout() {
		return true
	}
	return false
}