config

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 Item struct {
	// Meta 记录扩展元信息。
	Meta map[string]string `json:"meta"`
	// Version 表示配置版本号。
	Version string `json:"version"`
	// Content 是配置原始内容。
	Content []byte `json:"content"`
	// Encrypted 标识 Content 是否已加密。
	Encrypted bool `json:"encrypted"`
	// UpdatedAt 表示最近更新时间。
	UpdatedAt time.Time `json:"updated_at"`
	// UpdatedBy 表示最近更新人。
	UpdatedBy string `json:"updated_by"`
}

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 {
	// LoadMode 指定加载模式：local / remote。
	LoadMode 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 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 Query struct {
	// Key 是基础配置键。
	Key Key `json:"key"`

	// UserId 表示请求上下文中的用户标识。
	UserId string `json:"user_id"`
	// AppId 表示请求上下文中的应用标识。
	AppId string `json:"app_id"`
	// TenantId 表示请求上下文中的租户标识。
	TenantId string `json:"tenant_id"`

	// Tags 表示额外标签条件。
	Tags map[string]string `json:"tags"`
}

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

type Store interface {
	// Get 按配置键读取当前生效配置。
	Get(ctx context.Context, key Key) (*Item, error)
	// GetByQuery 按运行时上下文读取配置。
	GetByQuery(ctx context.Context, query Query) (*Item, error)
	// Put 写入当前生效配置。
	Put(ctx context.Context, key Key, item *Item) error
	// Delete 删除当前配置。
	Delete(ctx context.Context, key Key) error

	// PutVersion 写入版本快照并返回版本号。
	PutVersion(ctx context.Context, key Key, item *Item) (string, error)
	// GetVersion 读取指定版本快照。
	GetVersion(ctx context.Context, key Key, version string) (*Item, error)
	// ListVersions 列出版本号列表。
	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 WatchEvent struct {
	// Type 表示事件类型。
	Type EventType `json:"type"`
	// Key 表示事件对应的配置键。
	Key Key `json:"key"`
	// Item 表示事件携带的配置内容。
	Item *Item `json:"item"`
}

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