// health.go - the optional provider liveness capability. Self-hosted
// backends (an oMLX box on a Mac) are NOT always online: they sleep, reboot,
// move networks. Consumers of expensive single-shot capabilities (a 300 MB
// transcription upload) must be able to probe cheaply first and fail fast
// with a clear "provider offline" instead of a slow upload timeout.
// CheckHealth is advisory liveness, not a guarantee -- the provider can die
// between probe and use; real calls still handle their own errors.
//
// health.go - provider 可选存活能力. 自托管后端 (跑在 Mac 上的 oMLX) **不是**
// 常在线: 会睡眠 / 重启 / 换网络. 昂贵单次能力的消费者 (300 MB 转写上传) 必须
// 能先便宜探活, 快速失败并明确报 "provider 离线", 而不是慢速上传超时.
// CheckHealth 是参考性存活探测, 非保证 -- 探测与使用之间 provider 仍可能挂,
// 真调用仍需处理自己的错误.

package flyto

import "context"

// HealthChecker is the optional liveness probe capability. A provider whose
// backend exposes a health endpoint implements it; consumers type-assert
// (hc, ok := p.(flyto.HealthChecker)) and treat absence as "no probe
// available" (proceed), NOT as unhealthy. A non-nil error means the backend
// is unreachable or reported itself unhealthy.
//
// HealthChecker 是可选存活探测能力. 后端有健康端点的 provider 实现它; 消费者
// type-assert 并把缺失当 "无探测可用" (照常继续), **不是**不健康. 非 nil error
// 表示后端不可达或自报不健康.
type HealthChecker interface {
	CheckHealth(ctx context.Context) error
}