settings

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package settings 提供设置接缝(ctx.settings):分层作用域 + 路径操作 + CAS + 密钥脱敏。

对齐上游:packages/settings/settings + settings-file

设计要点:

  • SettingsScope 基于 pkg/scope 分层:host 层定义默认值,session 层可覆盖(nearest-wins);
  • 更新通过 SettingsPathOp{set/unset} 表达,携带 expectedRevision 做 CAS 乐观锁;
  • describe(redactSecrets:true) 对 secret 路径只输出 set/unset 操作位,value 全脱敏, 避免把密钥明文泄漏给模型或日志。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsRevisionMismatch

func IsRevisionMismatch(err error) bool

IsRevisionMismatch 判断是否为修订冲突错误。

Types

type DescribedSetting

type DescribedSetting struct {
	Path   Path   `json:"path"`
	Op     string `json:"op"` // "set" / "unset" / "default"
	Value  any    `json:"value,omitempty"`
	Secret bool   `json:"secret,omitempty"`
}

DescribedSetting 是 describe 输出的单条设置。

type ErrRevisionMismatch

type ErrRevisionMismatch struct {
	Expected uint64
	Actual   uint64
}

ErrRevisionMismatch 是 CAS 修订号冲突错误。

func (*ErrRevisionMismatch) Error

func (e *ErrRevisionMismatch) Error() string

Error 实现 error 接口。

type Path

type Path string

Path 是设置路径(如 "sandbox.mode",点分)。

type PathOp

type PathOp struct {
	// Set 非 nil 表示设置该路径为该值;否则表示 unset。
	Set *json.RawMessage `json:"set,omitempty"`
}

PathOp 是单个设置路径操作。

func NewSetOp

func NewSetOp(v any) PathOp

NewSetOp 构造 set 操作。

func NewUnsetOp

func NewUnsetOp() PathOp

NewUnsetOp 构造 unset 操作。

type SettingsNamespace

type SettingsNamespace struct {
	// Name 命名空间名。
	Name string
	// SecretPaths 属于密钥的路径集合(describe 时脱敏)。
	SecretPaths map[Path]struct{}
}

SettingsNamespace 描述一个设置命名空间(含哪些路径属于 secret)。

func NewNamespace

func NewNamespace(name string) *SettingsNamespace

NewNamespace 创建命名空间。

func (*SettingsNamespace) IsSecret

func (ns *SettingsNamespace) IsSecret(p Path) bool

IsSecret 判断路径是否密钥。

func (*SettingsNamespace) MarkSecret

func (ns *SettingsNamespace) MarkSecret(p Path)

MarkSecret 将某路径标记为密钥。

type SettingsScope

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

SettingsScope 是设置的作用域视图(host 层 + session 层)。

func NewSettingsScope

func NewSettingsScope(ns *SettingsNamespace) *SettingsScope

NewSettingsScope 创建设置作用域(host 层先建立)。

func (*SettingsScope) ApplyHost

func (s *SettingsScope) ApplyHost(path Path, value any) error

ApplyHost 设置 host 层默认值(expectedRevision=0 表示初始或强制)。

func (*SettingsScope) Describe

func (s *SettingsScope) Describe(redactSecrets bool) []DescribedSetting

Describe 输出当前设置描述。redactSecrets=true 时 secret 路径只给操作位不给明文。

func (*SettingsScope) Get

func (s *SettingsScope) Get(path Path) (json.RawMessage, bool)

Get 按 nearest-wins 读取路径值(返回原始 JSON 字节)。

func (*SettingsScope) Replace

func (s *SettingsScope) Replace(expectedRevision uint64, values map[Path]any) error

Replace 整体替换 session 层设置(CAS)。

func (*SettingsScope) Revision

func (s *SettingsScope) Revision() uint64

Revision 返回当前修订号(每次 update/replace 后递增)。

func (*SettingsScope) Update

func (s *SettingsScope) Update(expectedRevision uint64, ops map[Path]PathOp) error

Update 以 CAS 语义应用一组路径操作:

  • expectedRevision 必须等于当前 Revision,否则返回 ErrRevisionMismatch;
  • 每个 op 应用到 session 层(覆盖 host 层默认值);
  • 成功后 Revision +1。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL