runtimeserver

type Configuration interface {
	// ListProviders 按 id 顺序返回配置里的全部 Provider，带 API key 原文；同时返回模型配置的默认模型：models.default_model，
	// 没写时是按 Provider id、模型 id 排序的第一个模型，模型目录为空时是零值；defaults 是同次加载的模型默认配置。
	ListProviders(ctx context.Context) (providers []defs.ProviderConfig, defaultModel defs.ModelRef, defaults defs.ModelDefaults, err error)
	// SetProvider 把整份 Provider 写成 models/<id>.yaml（已有时整份替换）；defaultModel 不是零值时同时把 models.default_model 改成它，
	// 两个文件写完只重新加载一次，失败时都恢复。id 不合法时返回 invalid provider id，不碰文件。
	SetProvider(ctx context.Context, provider defs.ProviderConfig, defaultModel defs.ModelRef) (*runtime.Definitions, error)
	// DeleteProvider 删除 models/<id>.yaml，再重新加载配置；没有这个 Provider 时返回 provider <id> is not configured。
	DeleteProvider(ctx context.Context, providerID string) (*runtime.Definitions, error)
	// SetDefaultModel 只改配置文件里的 models.default_model，其余内容和注释保留，再重新加载配置；配置文件不存在时新建。
	SetDefaultModel(ctx context.Context, ref defs.ModelRef) (*runtime.Definitions, error)
	// Reload 不改任何文件，用启动时的配置路径和 flag 重新加载整份配置。
	Reload(ctx context.Context) (*runtime.Definitions, error)
}

type ModelCatalog interface {
	// ListCatalogProviders 返回模型目录里能对应上协议和 base_url 的服务；目录数据拿不到时返回错误。
	ListCatalogProviders(ctx context.Context) ([]defs.CatalogProvider, error)
	// ListCatalogModels 返回模型目录里一个服务的全部模型，key 是写进配置文件的模型 id；服务不在目录里时返回错误。
	ListCatalogModels(ctx context.Context, catalogProviderID string) (map[string]*defs.ProviderModelConfig, error)
	// FetchProviderModels 请求 Provider 上游的 /models 取模型 id，再按 id 从模型目录补字段；上游请求失败时返回错误。
	FetchProviderModels(ctx context.Context, provider defs.ProviderConfig) (map[string]*defs.ProviderModelConfig, error)
}

type RuntimeServer interface {
	// Run 监听并服务直到 ctx 结束、收到 shutdown 请求或空闲超时；返回前停止接受新连接，并关闭、等待全部已升级连接。只能调用一次。
	// 监听或服务失败时返回该错误；ctx 结束时返回 ctx.Err()；收到 shutdown 请求或空闲超时时返回 nil。
	Run(ctx context.Context) error
}

type RuntimeServerOpt struct {
	Runtime runtime.Runtime
	// Configuration 读写 serve 本机的模型配置，必须非 nil。
	Configuration Configuration
	// ModelCatalog 提供引导用的模型服务和模型，必须非 nil。
	ModelCatalog ModelCatalog
	// Listen 是 TCP 监听地址，例如 0.0.0.0:8790；Listener 非 nil 时忽略。
	Listen string
	// Listener 是调用方已建立的监听器；非 nil 时优先使用它，Run 返回前关闭。调用方可先写出实际地址再启动服务。
	Listener net.Listener
	// Token 是全部协议路由共用的访问令牌。
	Token string
	// ServerID 标识这台机器上的 serve，重启后保持不变，initialize 原样返回；客户端据此判断连上的是不是本机的 serve。
	ServerID string
	// Telemetry 是遥测管道，由 Run 挂到 ctx 供全部连接使用；nil 时使用全局兜底。
	Telemetry *telemetry.Telemetry
	// WebUI 是页面静态文件，根目录下有 index.html；nil 时不提供页面。
	WebUI fs.FS
	// IdleTimeout 大于 0 时，没有连接且 Runtime 空闲持续这么久后 Run 返回 nil；为 0 时常驻。
	IdleTimeout time.Duration
}