runtime

type AppService interface{}

type CircularDependencyError struct {
	Key   string   // the key that triggered the cycle
	Chain []string // the full resolution chain, e.g. ["A", "B", "A"]
}

type Container interface {
	// Bind registers a factory under a key.
	// If the key is already bound, a warning is logged and the previous binding is replaced.
	//
	// Bind 将 factory 绑定到目标 key。
	// 如果 key 已绑定，打印警告日志并替换原有绑定。
	Bind(key string, factory Factory, singleton bool)

	// NamedBind registers a named factory under a key.
	// Allows multiple implementations of the same key to coexist under different names.
	//
	// NamedBind 将命名 factory 绑定到目标 key。
	// 允许同一 key 的多个实现以不同名称共存。
	NamedBind(name, key string, factory Factory, singleton bool)

	// IsBind reports whether a key is bound.
	//
	// IsBind 返回指定 key 是否已绑定。
	IsBind(key string) bool

	// IsBindNamed reports whether a named binding exists.
	//
	// IsBindNamed 返回指定命名绑定是否存在。
	IsBindNamed(name, key string) bool

	// Make resolves a service by key.
	//
	// Make 按 key 解析服务。
	Make(key string) (any, error)

	// MakeNamed resolves a named service by name and key.
	//
	// MakeNamed 按名称和 key 解析命名服务。
	MakeNamed(name, key string) (any, error)

	// MustMake resolves a service by key and panics on error.
	//
	// MustMake 按 key 解析服务，失败时 panic。
	MustMake(key string) any

	// MustMakeNamed resolves a named service by name and key and panics on error.
	//
	// MustMakeNamed 按名称和 key 解析命名服务，失败时 panic。
	MustMakeNamed(name, key string) any

	// RegisterCloser registers an io.Closer to be called during Destroy.
	// Closers are called in reverse registration order.
	//
	// RegisterCloser 注册一个 io.Closer，在 Destroy 时调用。
	// Closer 按注册逆序调用。
	RegisterCloser(key string, closer io.Closer)

	// Destroy calls all registered closers in reverse order and marks the container as destroyed.
	// After Destroy, Make/MakeNamed return ErrContainerDestroyed.
	//
	// Destroy 按注册逆序调用所有 Closer，并将容器标记为已销毁。
	// 销毁后 Make/MakeNamed 返回 ErrContainerDestroyed。
	Destroy() error

	// RegisterProvider registers one provider into the container.
	//
	// RegisterProvider 将单个 provider 注册进容器。
	RegisterProvider(p ServiceProvider) error

	// RegisterProviders registers multiple providers into the container.
	//
	// RegisterProviders 将多个 provider 注册进容器。
	RegisterProviders(providers ...ServiceProvider) error

	// RegisteredProviders returns the names of all registered providers with their load/boot status.
	//
	// RegisteredProviders 返回所有已注册 provider 的名称及其加载/引导状态。
	RegisteredProviders() []ProviderInfo

	// DebugPrint returns a human-readable snapshot of the container state for diagnostics.
	//
	// DebugPrint 返回容器状态的人类可读快照，用于诊断。
	DebugPrint() string

	// ProviderDAG returns the provider dependency graph for visualization and analysis.
	// Useful for debugging provider load order and detecting circular dependencies.
	//
	// ProviderDAG 返回 provider 依赖图，用于可视化和分析。
	// 用于调试 provider 加载顺序和检测循环依赖。
	ProviderDAG() ProviderDAG
}

type Cron interface {
	// Add registers a cron job.
	//
	// Add 注册一个 cron 任务。
	Add(spec string, fn func(ctx context.Context) error) (entryID int, err error)

	// AddNamed registers a named cron job.
	//
	// AddNamed 注册一个具名 cron 任务。
	AddNamed(name, spec string, fn func(ctx context.Context) error) (entryID int, err error)

	// Start starts the cron scheduler.
	//
	// Start 启动 cron 调度器。
	Start()

	// Stop stops the cron scheduler and returns a context for shutdown coordination.
	//
	// Stop 停止 cron 调度器，并返回一个用于关闭协调的 context。
	Stop() context.Context

	// Jobs returns information about all registered cron jobs, including
	// schedule, last/next run time, and execution status.
	//
	// Jobs 返回所有已注册 cron 任务的信息，包括调度表达式、上次/下次执行时间及执行状态。
	Jobs() []CronJobEntry
}

type CronJobEntry struct {
	// ID is the unique entry identifier assigned by the scheduler.
	//
	// ID 是调度器分配的唯一任务标识。
	ID int `json:"id"`

	// Name is the human-readable job name. Empty for anonymous jobs.
	//
	// Name 是任务的可读名称。匿名任务为空。
	Name string `json:"name"`

	// Spec is the cron expression (e.g. "0 */5 * * * *").
	//
	// Spec 是 cron 表达式（如 "0 */5 * * * *"）。
	Spec string `json:"spec"`

	// Status is the last known execution status.
	//
	// Status 是最近一次执行的状态。
	Status CronJobStatus `json:"status"`

	// LastRunTime is the time of the last execution, zero if never run.
	//
	// LastRunTime 是上次执行时间，从未执行则为零值。
	LastRunTime time.Time `json:"last_run_time,omitempty"`

	// NextRunTime is the time of the next scheduled execution, zero if stopped.
	//
	// NextRunTime 是下次计划执行时间，已停止则为零值。
	NextRunTime time.Time `json:"next_run_time,omitempty"`

	// LastError is the error from the last execution, nil if succeeded or never run.
	//
	// LastError 是上次执行的错误，成功或从未执行则为 nil。
	LastError string `json:"last_error,omitempty"`

	// LastDuration is the duration of the last execution, zero if never run.
	//
	// LastDuration 是上次执行的耗时，从未执行则为零值。
	LastDuration time.Duration `json:"last_duration,omitempty"`
}

type CronJobStatus string

type CronRuntimeConfigurator interface {
	// ConfigureCronRuntime configures the cron runtime and returns the number of registered jobs.
	//
	// ConfigureCronRuntime 配置 cron 运行时，并返回注册任务数量。
	ConfigureCronRuntime(Container) (int, error)
}

type DAGEdge struct {
	From string // 依赖方 provider
	To   string // 被依赖方 provider（可能为空，表示依赖外部绑定）
	Key  string // 依赖的契约键
}

type Factory func(Container) (any, error)

type GRPCRuntimeBuilder interface {
	// BuildGRPCServer builds and returns a gRPC server.
	//
	// BuildGRPCServer 构建并返回一个 gRPC 服务端。
	BuildGRPCServer() *grpc.Server
}

type HTTPRuntimeConfigurator interface {
	// ConfigureHTTPRuntime configures the HTTP runtime.
	//
	// ConfigureHTTPRuntime 配置 HTTP 运行时。
	ConfigureHTTPRuntime(Container) error
}

type Host interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	Shutdown(ctx context.Context) error
	RegisterService(name string, service Hostable) error
	Services() []string
}

type Hostable interface {
	Name() string
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

type Lifecycle interface {
	OnStarting(ctx context.Context) error
	OnStarted(ctx context.Context) error
	OnStopping(ctx context.Context) error
	OnStopped(ctx context.Context) error
}

type ProviderDAG struct {
	Nodes     []ProviderDAGNode // 所有节点
	Edges     []DAGEdge         // 依赖边
	Cycles    [][]string        // 检测到的循环依赖
	LoadOrder []string          // 推荐加载顺序
}

type ProviderDAGNode struct {
	Name      string   // Provider 名称
	Provides  []string // 提供的契约键
	DependsOn []string // 依赖的契约键
	IsDefer   bool     // 是否延迟加载
	Loaded    bool     // 是否已加载
	Booted    bool     // 是否已启动
}

type ProviderInfo struct {
	Name    string
	Loaded  bool
	Booted  bool
	IsDefer bool
}

type Root interface {
	BasePath() string
	StoragePath() string
	RuntimePath() string
	LogPath() string
	ConfigPath() string
	TempPath() string
}

type ServiceProvider interface {
	// Name returns the unique provider name.
	//
	// Name 返回唯一的 provider 名称。
	Name() string

	// Register binds provider services into the container.
	//
	// Register 将 provider 服务绑定到容器中。
	Register(c Container) error

	// Boot performs boot-time initialization after registration.
	//
	// Boot 在注册完成后执行启动期初始化。
	Boot(c Container) error

	// IsDefer reports whether registration should be deferred until needed.
	//
	// IsDefer 表示该 provider 是否应延迟到真正需要时再装载。
	IsDefer() bool

	// Provides returns the keys that can be resolved from this provider.
	//
	// Provides 返回该 provider 可以提供的 key 列表。
	Provides() []string

	// DependsOn returns the keys that this provider depends on.
	// Used for dependency graph construction and load order computation.
	//
	// DependsOn 返回该 provider 依赖的 key 列表。
	// 用于构建依赖图和计算加载顺序。
	DependsOn() []string
}

type UnitOfWork interface {
	// Do executes the callback within the unit-of-work boundary.
	//
	// Do 在工作单元边界内执行回调。
	Do(ctx context.Context, fn func(ctx context.Context) error) error
}