lynx

type App interface {
	AppContext
	// Command 注册启动的命令，用于 CLI 模式。选项经 opts 传入
	// （WithMaxTries / WithBackoff / WithProbeTimeout / WithCommandName）。
	Command(cmd CommandFunc, opts ...CommandOption) error

	// OnPreStart 注册应用启动阶段执行的钩子函数：先于所有服务启动
	// 顺序执行，首个错误中止启动（已 Init 的服务逆序停止）。
	OnPreStart(fns ...HookFunc)
	// OnDrain 注册排水阶段执行的钩子函数：关停时 drainChecker 置位后
	// 与 DrainTimeout 窗口睡眠并发执行（如从服务目录注销），窗口即
	// 钩子总预算——窗口结束（无论钩子是否完成）即继续后续关停。
	// 必须启用排水（WithDrainTimeout，> 0）：DrainTimeout=0 时整段
	// 禁用，此时注册钩子由 Run() 返回 ErrDrainHooksRequireDrainTimeout。
	// 除手动注册外，实现 Drainer 接口的服务在 Register 登记时由框架
	// 自动挂载排水钩子（见 service.go），应用侧无需重复挂钩。
	OnDrain(fns ...HookFunc)
	// OnPreStop 注册应用停止阶段执行的钩子函数：先于服务 Stop 执行
	// （此时服务仍在服务在途请求，适合"停止接收前的最后冲刷"，不适合
	// 释放在途请求还要用的底层资源——那类资源放 OnPostStop）。服务进入
	// 运行阶段后，所有退出路径（信号/Close/服务失败/钩子失败/命令完成）
	// 都保证此顺序；Init/OnPreStart 失败路径不执行本阶段。
	OnPreStop(fns ...HookFunc)
	// OnPostStart 注册服务启动后执行的"运行通知"钩子：所有服务 actor
	// 进入执行体（Start 调用紧随其后，可能与钩子的最初几条指令并发）、
	// run group 进入运行态后顺序执行。阻塞型服务（HTTP/gRPC server）
	// 的 Start 直到关停才返回，故不存在"所有 Start 已返回"的时刻——
	// 钩子触发不代表端口已监听或就绪（就绪语义用健康检查表达）。钩子
	// 错误视为启动失败，触发整个应用的关停并随 Run() 上抛。
	OnPostStart(fns ...HookFunc)
	// OnPostStop 注册进程收尾清理钩子：所有服务 Stop、总线关停之后、
	// Run 返回前逆序执行（LIFO，与 defer/Wire cleanup 语义一致），总预算
	// CleanupTimeout（默认 10 秒），超时记日志并跳过剩余钩子，不阻塞
	// 进程退出。用于释放 DI 底层资源（DB/Redis 连接池等）。签名是无
	// 错误返回的 CleanupFunc：终局阶段错误没有消费者。Run 的所有退出
	// 路径（含服务 Init 失败、PreStart 失败）都会执行；Run 从未调用时
	// 由 Close() 兜底。
	OnPostStop(fns ...CleanupFunc)
	// Register 注册需要由应用托管生命周期的服务实例。
	// 服务的 Init 在注册时同步执行；注册阶段产生的错误不会立即返回，
	// 首个错误会被记录，并在 Run() 时统一返回。
	// 所有注册必须先于 Run 与 Close：Run 开始后或 Close 之后调用将 panic。
	Register(services ...Service)
	// RegisterFactory 注册需要由应用托管生命周期的服务工厂，
	// 错误处理语义与 Register 相同；同样必须先于 Run 与 Close。
	RegisterFactory(factories ...ServiceFactory)

	// Run 运行应用主流程：执行 on-pre-start 钩子、启动所有服务并等待退出信号。
	// Run 开始后或 Close 之后，Register/RegisterFactory 为禁止操作（panic），
	// Command 返回错误。
	Run() error
}

type AppContext interface {
	// Context 获取应用上下文
	Context() context.Context
	// Config 获取配置实例（默认由 *viper.Viper 适配实现）
	Config() Config
	// Logger 获取 logger
	Logger(kwargs ...any) *slog.Logger
	// Bus 获取应用级消息总线（一等对象，开箱即为内存实现，可被 Watermill/Kafka 装饰）。
	Bus() eventbus.Bus
	// HealthCheckers 返回当前已注册的健康检查器快照（注册时收集）。
	HealthCheckers() []Checker
	// Close 关闭应用实例（如一次性命令执行完毕）。
	Close()
}

type BindConfigFunc func(f *pflag.FlagSet, c ConfigSource) error

type BindFlagsFunc func(f *pflag.FlagSet)

type Checker interface {
	CheckHealth() error
}

type CleanupFunc func()

type Clock interface {
	Now() time.Time
	// After 在 d 之后向返回的 channel 发送当前时间（语义同 time.After）。
	After(d time.Duration) <-chan time.Time
}

type CommandFunc func(ctx context.Context) error

type CommandOption func(*CommandOptions)

type CommandOptions struct {
	Name           string
	MaxTries       uint
	InitialBackoff time.Duration
	MaxBackoff     time.Duration
	// ProbeTimeout bounds a single dependency probe (one CheckHealth
	// call or one Ready-channel wait). A probe that exceeds it counts
	// as "not ready this round" and joins the backoff retry loop.
	ProbeTimeout time.Duration
	// WaitBudget is the wall-clock budget for the whole dependency wait.
	// 0 (default) means unlimited: only the attempts/backoff round budget
	// applies. Non-zero caps the total wait; whichever budget is reached
	// first wins (Wait budget semantics).
	WaitBudget time.Duration
}

type Config interface {
	// Get 返回 path 对应的值，未设置时返回 nil。
	Get(path string) any
	// GetString 返回 path 对应的字符串值。
	GetString(path string) string
	// GetBool 返回 path 对应的布尔值。
	GetBool(path string) bool
	// GetInt 返回 path 对应的整数值。
	GetInt(path string) int
	// GetStringMap 返回 path 对应的键值映射。
	GetStringMap(path string) map[string]any
	// GetStringSlice 返回 path 对应的字符串切片。
	GetStringSlice(path string) []string
	// IsSet 报告 path 是否已设置。
	IsSet(path string) bool
	// Unmarshal 将配置解码到 out 指向的结构体。结构体目标默认走结构体驱动的
	// 逐叶取值：tag 回退链 mapstructure → json → 小写字段名，仅在环境变量
	// 设置的键（配置文件无此键）也参与解码；非结构体目标（map 等，无法
	// 枚举叶子）回落 viper 语义。通过 opts 选择或定制解码行为（见 UnmarshalOption）。
	Unmarshal(out any, opts ...UnmarshalOption) error
	// UnmarshalKey 将 path 对应的配置子树解码到 out 指向的结构体；
	// opts 语义与 Unmarshal 相同，叶子键以 path 为前缀。
	UnmarshalKey(path string, out any, opts ...UnmarshalOption) error
}

type ConfigSource interface {
	Config
	// Set 设置 path 的值。
	Set(path string, value any)
	// SetFile 设置配置文件路径。
	SetFile(path string)
	// AddSearchPath 添加配置文件搜索目录。
	AddSearchPath(dir string)
	// SetFileFormat 设置配置文件格式（如 yaml、json）。
	SetFileFormat(format string)
	// SetEnvPrefix 设置环境变量前缀。
	SetEnvPrefix(prefix string)
	// SetEnvKeyReplacer 设置环境变量键名替换规则，用于把点分路径键映射为
	// 环境变量名（如 "." → "_"），使任意键都能被环境变量覆盖。
	SetEnvKeyReplacer(repl *strings.Replacer)
	// AutomaticEnv 启用环境变量自动匹配。
	AutomaticEnv()
	// BindEnv 将 path 绑定到环境变量；env 为空时使用 path 的默认环境变量形式。
	BindEnv(path string, env ...string) error
}

type Drainer interface {
	DrainHook() HookFunc
}

type EventHandler[T any] interface {
	// Topic 返回订阅的类型化主题。
	Topic() eventbus.Topic[T]

	// HandlerName 是 Bus 内全局唯一的 handler 名，同时用作服务名
	//（启动/停止日志中的标识）。空名在 Init 期报错。
	HandlerName() string

	// Init 是依赖注入点：EventHandlerService 保证它在订阅之前调用，可用
	// AppContext 获取构造期不可得的依赖（配置、日志等）；无依赖时返回 nil。
	// 返回错误则不订阅，由 app.Run() 统一上抛。
	Init(ctx AppContext) error

	// Handle 处理一条已解码的事件。返回错误时按订阅选项重试或确认
	//（重试 / AutoAck / ContinueOnError 语义由 Bus 与 SubscribeOption 决定）。
	Handle(ctx context.Context, event *eventbus.Event[T]) error
}

type EventHandlerService[T any] struct {
	// contains filtered or unexported fields
}

type FactoryOptions struct {
	Instances int `json:"instances"` // 实例数
}

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

type HealthCheckersFunc func() []Checker

type HookFunc func(ctx context.Context) error

type Lifecycle interface {
	Init(ctx AppContext) error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

type Metadata struct {
	// Name is the application name.
	Name string
	// ID is the instance ID (hostname by default).
	ID string
	// Version is the application version.
	Version string
}

type Option func(*Options)

type Options struct {
	ID             string         `json:"id"`
	Name           string         `json:"name"`
	Version        string         `json:"version"`
	BindFlagsFunc  BindFlagsFunc  `json:"-"`
	BindConfigFunc BindConfigFunc `json:"-"`
	ExitSignals    []os.Signal    `json:"-"`
	Bus            eventbus.Bus   `json:"-"`
	// BusProvider 非 nil 且 WithBus 未注入时，在配置装配完成后由框架调用
	// 以构造应用总线（依赖配置的总线如 watermill.NewFromConfig）及其配套
	// 服务（如 kafka Transport）。与 WithBus 并存时 WithBus 优先。
	BusProvider func(cfg Config) (eventbus.Bus, []Service, error) `json:"-"`
	// LoggerProvider 非 nil 时，在配置装配与元数据解析完成后、总线构造前
	// 由框架调用，产出应用 logger（依赖配置与 meta 的 logger，如
	// contrib/zap 的 NewLogger）。配置了 provider 时框架跳过 logging.level
	// 的默认 TextHandler 重建（applyLogLevel）——级别归 provider 自己的
	// 装配逻辑（zap 侧从 ctx.Config() 读取）。
	LoggerProvider func(ctx AppContext) (*slog.Logger, error) `json:"-"`
	// ConfigWatch 启用配置文件热更新（WithConfigWatch）：Run 启动期注册
	// viper WatchConfig，文件变更时框架经总线发布 lynx.config.updated
	// 事件（eventbus.ConfigUpdatedTopic），后续 Config() 读取返回新值；
	// 订阅方自行决定响应粒度。要求配置来自文件，否则 Run 启动期报错。
	ConfigWatch bool `json:"-"`

	ShutdownTimeout time.Duration `json:"shutdown_timeout"`
	// StopTimeout 是单个服务 Stop 的最长等待时长，超过后跳过并记录错误，
	// 防止挂死的服务阻塞整个关停流程。
	// ShutdownTimeout 与 StopTimeout 的 0 均表示"未设置"：EnsureDefaults
	// 会折叠为默认值，无法显式表达"禁用上界"（注意与 server 侧
	// ShutdownTimeout=0 的"无上界"语义不同）。
	StopTimeout time.Duration `json:"stop_timeout"`
	// DrainTimeout 是关停排水（drain）窗口时长，v1.10.0 起同时是
	// OnDrain 钩子的总预算（DrainHookTimeout 已并入）：关停时先让
	// readiness 失败（LB 摘流），OnDrain 钩子（如从服务目录注销）与
	// 窗口睡眠并发执行，窗口结束时无论钩子是否完成都继续后续关停。
	// 0（默认）表示不启用排水——整段（窗口与钩子）禁用；此时注册了
	// OnDrain 钩子会在 Run() 启动期返回 ErrDrainHooksRequireDrainTimeout。
	// 与 ShutdownTimeout 是独立预算：总关停时长上界 =
	// DrainTimeout + ShutdownTimeout + 各服务 StopTimeout 叠加 + CleanupTimeout。
	// 取值任意 ≥0，无下限约束（1ms 等小值合法）。
	DrainTimeout time.Duration `json:"drain_timeout"`
	// BusReadyTimeout 是 newLynx 构造应用时等待消息总线就绪
	// （CheckHealth 通过）的总预算，默认 10 秒：Watermill+Kafka 等
	// 慢启动后端需要比 1 秒级硬编码更宽的就绪窗口。0 表示使用默认值
	//（无法显式禁用等待——总线就绪是构造成功的硬前提）；负值在
	// Validate 时报错。
	BusReadyTimeout time.Duration `json:"bus_ready_timeout"`
	// CleanupTimeout 是 OnPostStop 收尾钩子的总预算（默认 10 秒）：
	// 所有服务与总线停止之后、Run 返回前，逆序执行收尾钩子（关闭
	// DB/Redis 连接池等 DI 底层资源）。与 ShutdownTimeout 是独立预算：
	// 总关停时长上界 = 排水段 + ShutdownTimeout + 各服务 StopTimeout
	// 叠加 + CleanupTimeout。0 表示使用默认值；负值在 Validate 时报错。
	CleanupTimeout time.Duration `json:"cleanup_timeout"`

	// Config 非 nil 时作为应用配置直接采用（WithConfig 注入）：构造期跳过
	// flags 解析与配置文件装配（BindFlagsFunc/BindConfigFunc 不再执行），
	// os.Args 与工作目录不参与配置。用于测试与宿主进程注入。
	Config Config `json:"-"`
	// contains filtered or unexported fields
}

type OrderedOption func(*orderedServices)

type Ready interface {
	Ready() <-chan struct{}
}

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

type Server interface {
	Service
	// Addr 返回实际监听地址：Start 前（或 Listen 失败时）返回空字符串；
	// 使用随机端口（如 ":0"）时返回 Listen 成功后的实际地址。
	Addr() string
	// AdvertiseAddr 返回 WithAdvertiseAddr 设置的对外宣告地址；未设置时
	// 返回空字符串。
	AdvertiseAddr() string
	// Ready 在 Listen 成功之后、Serve 之前关闭（语义同 Ready 接口）。
	Ready() <-chan struct{}
}

type Service interface {
	Name() string
	Lifecycle
}

type ServiceFactory interface {
	New() Service
	Options() FactoryOptions
}

type SetupFunc func(app App) error

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

type UnmarshalOption func(*UnmarshalOptions)

type UnmarshalOptions struct {
	// TagName 非空时仅按该 struct tag 匹配配置键（无 tag 的字段按
	// 小写字段名匹配）。空值按 mapstructure → json → 小写字段名回退。
	TagName string
	// StrictTypes 拒绝非字符串标量到集合的弱类型转换（如 brokers: 42 被
	// 静默弱转为 []string{"42"}）：启动期报错优于静默错值。字符串来源的
	// 弱转不受影响——环境变量注入的值恒为字符串（"a,b" → 切表、"42" →
	// int 均为合法弱转），拒绝字符串会使 env 覆盖不可用。
	StrictTypes bool
	// ErrorUnused 报告配置子树中未被目标结构体消费的键（未知键，多为
	// 拼写错误）。仅 UnmarshalKey 支持（需要可枚举的配置子树，Unmarshal
	// 传入时返回明确错误）；动态键的 map 字段整体视为已消费。
	ErrorUnused bool
}