config

type BootstrapConfig interface {
	GetAppId() string
	GetAppSecret() string
	GetAppName() string
	GetAppVersion() string
	GetServiceEndpoint() string
	GetServiceAuthToken() string
	GetServiceNamespace() string
	GetServiceInstanceId() string

	GetSystemName() string
	GetSystemType() uint32
	GetSystemVersion() string

	GetGatewayEndpoint() string
	GetGatewayAuthToken() string

	GetServerPort() uint
	GetManagementPort() uint

	LoggerConfig
	TelemetryConfig
}

type Codec interface {
	// Marshal 把结构化对象编码为字节。
	Marshal(v any) ([]byte, error)
	// Unmarshal 把字节解码到目标对象。
	Unmarshal(data []byte, dst any) error
}

type Encryptor interface {
	// Encrypt 使用给定密钥加密数据。
	Encrypt(data []byte, key []byte) ([]byte, error)
	// Decrypt 使用给定密钥解密数据。
	Decrypt(data []byte, key []byte) ([]byte, error)
}

type EventType int

type Key struct {
	// TenantId 表示租户标识，用于多租户隔离。
	TenantId string `json:"tenant_id"`
	// AppId 表示应用标识。
	AppId string `json:"app_id"`
	// Env 表示环境，如 dev/staging/prod。
	Env string `json:"env"`

	// Group 表示配置分组。
	Group string `json:"group"`
	// Name 表示具体配置名。
	Name string `json:"name"`
}

type LoaderParams struct {
	// Mode 指定加载模式：local / remote。
	Mode string
	// AppId 远程模式下用于定位配置所属应用。
	AppId string
	// AppSecret 远程模式下用于解密整份配置内容（如果是密文）。
	AppSecret []byte
	// Group 配置分组（如 database）。
	Group string
	// Key 配置名（如 consul / etcd / k8s）。
	Key string
	// FileName 本地模式下使用的文件名（如 consul.json）。
	FileName string
}

type LocalLoaderFunc func(fileName string, target any) error

type LoggerConfig interface {
	GetLoggerConsole() bool
	GetLoggerRemote() bool
}

type Meta struct {
	// CurrentVersion 表示当前生效版本。
	CurrentVersion string `json:"current_version"`
	// LatestVersion 表示最新发布版本。
	LatestVersion string `json:"latest_version"`
}

type Option func(*Options)

type Options struct {
	// Namespace 用于区分配置键空间。
	Namespace string
	// Timeout 用于单次请求超时控制。
	Timeout time.Duration
	// Retry 用于失败重试次数控制。
	Retry uint32
	// WatchBuffer 用于监听事件通道缓冲区大小。
	WatchBuffer int
	// Codec 为可选编解码器。
	Codec Codec
	// Encryptor 为可选加解密器。
	Encryptor Encryptor
}

type PayloadDecodeFunc func(content string, secret []byte, target any) error

type Raw struct {
	// Meta 记录扩展元信息。
	Meta map[string]string `json:"meta"`
	// Version 表示配置版本号。
	Version string `json:"version"`
	// Content 是当前整份配置的原始内容。
	Content []byte `json:"content"`
	// Encrypted 标识当前整份 Content 是否已加密。
	// 当值为 true 时，读取方必须先解密整份内容，再做反序列化。
	Encrypted bool `json:"encrypted"`
	// CreatedAt 表示创建时间。
	CreatedAt time.Time `json:"created_at"`
	// UpdatedAt 表示最近更新时间。
	UpdatedAt time.Time `json:"updated_at"`
	// UpdatedBy 表示最近更新人。
	UpdatedBy string `json:"updated_by"`
}

type RemoteLoaderFunc func(appId, group, key string) (string, error)

type Store interface {
	// Get 按配置键读取当前生效配置。
	// 读取到的 Raw.Encrypted 标识整份配置是否为密文。
	// 当 Encrypted=true 时，调用方需要先解密整份 Content，再解析目标结构。
	Get(ctx context.Context, key Key) (*Raw, error)

	// Put 写入当前生效配置。
	// Raw.Encrypted 标识整份配置是否为密文。
	// 一份配置要加密就整份加密，不做字段级加密。
	Put(ctx context.Context, key Key, raw *Raw) error

	// Delete 删除当前配置。
	Delete(ctx context.Context, key Key) error

	// PutVersion 写入版本快照并返回版本号。
	// 若 Raw.Version 为空，实现层可自动生成版本号。
	PutVersion(ctx context.Context, key Key, raw *Raw) (string, error)

	// GetVersion 读取指定版本快照。
	GetVersion(ctx context.Context, key Key, version string) (*Raw, error)

	// ListVersions 列出版本号列表。
	// limit 为 0 时返回所有版本，否则返回最新的 limit 个版本。
	ListVersions(ctx context.Context, key Key, limit int) ([]string, error)

	// GetMeta 读取配置元信息。
	GetMeta(ctx context.Context, key Key) (*Meta, error)

	// PutMeta 写入配置元信息。
	PutMeta(ctx context.Context, key Key, meta *Meta) error
}

type StoreParams struct {
	// Key 是优先使用的业务键。
	Key Key
	// AppId 用于回填 Key.AppId。
	AppId string
	// Env 用于回填 Key.Env。
	Env string
	// Group 用于回填 Key.Group。
	Group string
	// Name 用于回填 Key.Name。
	Name string
	// AppSecret 当读取到密文配置项时用于解码。
	AppSecret []byte
}

type TelemetryConfig interface {
	GetOtelEndpoint() string
	GetOtelInsecure() bool

	GetOtelTraces() bool
	GetOtelMetrics() bool
	GetOtelLogs() bool
}

type WatchEvent struct {
	// Type 表示事件类型。
	Type EventType `json:"type"`
	// Key 表示事件对应的配置键。
	Key Key `json:"key"`
	// Raw 表示事件携带的配置内容。
	Raw *Raw `json:"raw"`
}

type Watcher interface {
	// Watch 监听指定配置键的变更事件。
	Watch(ctx context.Context, key Key) (<-chan WatchEvent, error)
	// Unwatch 取消指定配置键的监听。
	Unwatch(key Key)
}