retry

type AnthropicRetryOpts struct {
	// MaxRetries 最大重试次数(默认 10)
	MaxRetries int
	// IsSubscriber 是否为订阅用户
	IsSubscriber func() bool
	// IsEnterprise 是否为企业用户
	IsEnterprise func() bool
	// IsFastMode 是否在快速模式
	IsFastMode func() bool
	// OnFastModeCooldown 快速模式冷却回调
	OnFastModeCooldown func(duration time.Duration, reason string)
	// OnFastModeDisable 快速模式永久禁用回调
	OnFastModeDisable func(reason string)
	// FallbackThreshold 触发模型降级的连续 529 次数(默认 3)
	FallbackThreshold int
}

type CannotRetryError struct {
	// Original 是最后一次尝试的错误
	Original error
	// Attempts 总尝试次数
	Attempts int
	// Reason 放弃重试的原因
	Reason string
}

type CompositeRetryPolicy struct {
	// contains filtered or unexported fields
}

type ConsecutiveLimit struct {
	// Category 要追踪的错误类别字符串(如 "server_overload")
	Category string
	// Limit 连续出现次数上限
	Limit int
}

type ContextOverflowHandler struct {
	// FloorOutputTokens 输出 token 最低保障(默认 3000)
	// 即使上下文快满了,也至少留这么多 token 给输出.
	// 低于此值意味着没有足够空间生成有用回复,不如直接失败.
	FloorOutputTokens int
	// SafetyBuffer 安全余量(默认 1000)
	// 防止因 token 估算误差导致再次溢出.
	SafetyBuffer int
	// ThinkingBudget 当前 thinking token 预算(0=未启用 thinking)
	// max_tokens 必须能容纳 thinking budget + 至少 1 个 output token.
	ThinkingBudget int
}

type ExponentialBackoff struct {
	// BaseDelay 初始退避时间(默认 500ms)
	BaseDelay time.Duration
	// MaxDelay 最大退避时间上限(默认 32s)
	MaxDelay time.Duration
	// MaxRetries 最大重试次数(默认 10)
	MaxRetries int
	// JitterPct 抖动比例(默认 0.25 = 25%)
	JitterPct float64
}

type FallbackTriggeredError struct {
	OriginalModel string
	FallbackModel string
	Original      error
}

type FastModeCooldown struct {
	// IsFastMode 判断当前是否在快速模式
	IsFastMode func() bool
	// ShortRetryThreshold 短延迟阈值(低于此值保持快速模式)
	ShortRetryThreshold time.Duration
	// CooldownDuration 默认冷却时间(retry-after 未知时使用)
	CooldownDuration time.Duration
	// MinCooldown 最低冷却时间(防止过快切回导致反复抖动)
	MinCooldown time.Duration
	// OnCooldownStart 进入冷却期回调(上层据此切换模型)
	OnCooldownStart func(duration time.Duration, reason string)
	// OnPermanentDisable overage 被拒绝时永久禁用回调
	OnPermanentDisable func(reason string)
}

type ForegroundOnly struct{}

type MaxAttemptsLimit struct {
	Max int
}

type ModelFallback struct {
	// ConsecutiveThreshold 触发降级的连续过载次数
	ConsecutiveThreshold int
}

type OverflowInfo struct {
	InputTokens  int // 实际输入 token 数
	MaxTokens    int // 当前设置的 max_tokens
	ContextLimit int // 模型的上下文窗口上限
}

type RetryContext struct {
	// QuerySource labels the caller ("main_thread"/"summary"/"compact"/...)
	// so retry-layer diagnostics can attribute a failed retry to its origin.
	// It is a free-form string (not an enum) so third-party providers and
	// call sites outside pkg/engine can add their own source labels without
	// touching retry-layer types.
	//
	// Wire: callers inject via retry.WithQuerySource(ctx, s); transport
	// Client reads it via retry.QuerySourceFromCtx(ctx) into this field at
	// rctx construction (internal/transport/client.go). Retryer.Do embeds
	// it into CannotRetryError.Reason so an operator watching the error
	// stream sees "policy denied (source=compact)" instead of opaque
	// "policy denied". Future retry policies may branch on this field
	// (e.g. be more aggressive about dropping background sources), but the
	// field is deliberately not yet policy-reading -- diagnostics first,
	// behavior changes only after data.
	//
	// QuerySource 标记请求调用方 ("main_thread"/"summary"/"compact" 等)
	// 让重试层诊断把失败重试归因到来源. 自由字符串 (非枚举), 第三方
	// provider 和 pkg/engine 外的 call site 可以加自定义标签, 不需要碰
	// 重试层类型.
	//
	// Wire: 调用方经 retry.WithQuerySource(ctx, s) 注入; transport Client
	// 经 retry.QuerySourceFromCtx(ctx) 在 rctx 构造时填充此字段
	// (internal/transport/client.go). Retryer.Do 将其嵌入
	// CannotRetryError.Reason, 运维在错误流中看到 "policy denied
	// (source=compact)" 而不是含糊的 "policy denied". 未来重试策略可
	// 按此字段分支 (如对后台来源更激进地放弃), 但当前字段**不**被策略
	// 读 -- 先诊断, 行为变更需数据支撑.
	QuerySource string
	// IsForeground 用户是否在等结果.
	// 精妙之处(CLEVER): 调用方声明式标注,而非重试模块维护白名单.
	// 早期方案用 FOREGROUND_529_RETRY_SOURCES Set 硬编码 15+ 来源--每加一种要改重试模块.
	// 声明式方式:调用方设 IsForeground=true,重试模块只读.
	// 替代方案:<原方案在重试模块中维护前景来源白名单>
	IsForeground bool
	// StartTime 首次尝试时间(用于计算总耗时上限)
	StartTime time.Time
	// MaxDuration 最大总重试时长(0=不限制,仅受 MaxRetries 控制)
	// 升华改进(ELEVATED): 仓储 daemon 模式需要 "尽力重试但有上限",
	// 不是早期方案的 "无限重试" 也不是 "固定次数后放弃".
	MaxDuration time.Duration
	// ConsecutiveCounts 按错误类别统计连续出现次数.
	// 精妙之处(CLEVER): 由 Retryer 在每次失败后自动维护--
	// 连续出现同一类错误递增,出现不同类错误清零.
	// ConsecutiveLimit 策略读取此字段做决策.
	ConsecutiveCounts map[string]int
	// Model 当前使用的模型(用于模型降级策略)
	Model string
	// FallbackModel 降级模型(用于模型降级策略)
	FallbackModel string
	// MaxTokensOverride 被溢出修正调整过的 max_tokens(0=未调整)
	MaxTokensOverride int
}

type RetryDecision struct {
	// Retry 是否重试
	Retry bool
	// Delay 建议的等待时间
	Delay time.Duration
	// Reason 决策原因(可观测性:为什么重试/不重试)
	Reason string
}

type RetryError interface {
	Error() string
	Category() string
	IsRetryable() bool
	RetryDelay() time.Duration
	Message() string
	Headers() http.Header
	RetryInfo() *RetryInfo
}

type RetryInfo = apierror.RetryInfo

type RetryPolicy interface {
	ShouldRetry(err RetryError, attempt int, ctx *RetryContext) *RetryDecision
}

type RetryableFunc func(attempt int, rctx *RetryContext) error

type Retryer struct {
	// Policy 重试策略
	Policy RetryPolicy
	// OverflowHandler 溢出修正器(可选)
	OverflowHandler *ContextOverflowHandler
	// OnRetry 每次重试前的回调(用于可观测性,可选).
	// 参数:错误,第几次尝试,等待时间,决策原因.
	OnRetry func(err RetryError, attempt int, delay time.Duration, reason string)
	// Clock 时间源(可测试,nil 使用 time.Now)
	Clock func() time.Time
}

type ServerDirective struct{}

type SubscriptionAwareRetry struct {
	// IsSubscriber 判断当前用户是否为订阅用户(Pro/Max)
	IsSubscriber func() bool
	// IsEnterprise 判断当前用户是否为企业用户
	IsEnterprise func() bool
}