scope

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: 3 Imported by: 0

Documentation

Overview

本文件补充官方 scope 的父作用域链(bindScopeParent / scopeParentOf / scopeChainOf)。

作用域除了"层栈叠加",还可以显式声明自己的外层(父)作用域,从而在解析时沿 祖先链向上回溯。父关系是一张有向无环图:任何绑定都会做环检测,沿父链若能走回 起点,说明会成环,立即拒绝——因为所有链消费者都要沿父走到根。

Package scope 提供分层作用域注册表(ScopedLayers)原语。

对齐上游:packages/core/scope

设计动机:

  • omnix 的 Tools / Skills / Commands / Credentials 等注册表都存在"宿主级(host)定义 + 会话级 / 用户级 / 项目级覆盖"的需求, 例如:预设定义了一批工具,会话级可以隐藏其中某个;宿主级 deny 的凭据,作用域级可以 exempt;
  • 本包用一套通用的「分层 + 合并 + 解析」实现复用于所有注册表,避免每个注册表各写一套作用域叠加逻辑。

解析规则(与上游一致):

  1. nearest-scope-wins:从最近的作用域层向 host 层逐层查找,先命中的层决定值;
  2. rank:同一层内同 key 存在多个注册时,rank 大者胜;
  3. 后注册覆盖先注册:rank 相同时,注册时间靠后者胜;
  4. 匿名 entry(未命名)与 named entry(具名)互不冲突:匿名条目不参与具名查找, 仅在整体遍历时按注册顺序出现。

Index

Constants

This section is empty.

Variables

View Source
var ErrAlreadyBound = errors.New("scope: key already bound to a parent")

ErrAlreadyBound 表示某 key 已绑定父,重复绑定被拒。

View Source
var ErrCycle = errors.New("scope: parent link would form a cycle")

ErrCycle 表示该父绑定会形成环。

Functions

This section is empty.

Types

type Key

type Key string

Key 标识一个作用域层(如 "host"、"user:xxx"、"session:xxx"、"project:xxx")。

type Layer

type Layer[V any] struct {
	// contains filtered or unexported fields
}

Layer 是单层作用域(同一 ScopeKey 下的条目集合)。 内部使用切片保留注册顺序,保证后注册覆盖先注册的确定性。

func NewLayer

func NewLayer[V any](key Key) *Layer[V]

NewLayer 创建指定作用域键的空层。

func (*Layer[V]) Get

func (l *Layer[V]) Get(name string) (V, bool)

Get 是本层内的具名查找(导出版本,供外部判断某值是否存在于本层)。

func (*Layer[V]) Has

func (l *Layer[V]) Has(name string) bool

Has 判断本层是否存在该具名条目。

func (*Layer[V]) Key

func (l *Layer[V]) Key() Key

Key 返回该层的唯一标识。

func (*Layer[V]) Register

func (l *Layer[V]) Register(name string, value V, rank int) uint64

Register 向本层注册一条记录。

  • name 为空表示匿名 entry;
  • rank 越大优先级越高(同一层内同 key 冲突时);
  • 返回注册序号(供调用方构造依赖顺序时使用)。

func (*Layer[V]) Unregister

func (l *Layer[V]) Unregister(name string)

Unregister 从本层移除所有匹配该 name 的具名条目(匿名条目不受影响)。

type ParentTree

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

ParentTree 是作用域父关系注册表,并发安全。

func NewParentTree

func NewParentTree() *ParentTree

NewParentTree 创建空父关系表。

func (*ParentTree) Bind

func (t *ParentTree) Bind(key, parent Key) error

Bind 把 parent 绑定为 key 的父作用域(一次性)。

  • key 已有父 → ErrAlreadyBound;
  • 沿 parent 向上若遇到 key(会成环)→ ErrCycle。

func (*ParentTree) ChainOf

func (t *ParentTree) ChainOf(key Key) []Key

ChainOf 返回 key → 根祖先的链(nearest-first:[key, parent, grandparent, …])。

func (*ParentTree) ParentOf

func (t *ParentTree) ParentOf(key Key) (Key, bool)

ParentOf 返回 key 的父;根作用域返回 false。

func (*ParentTree) Rebind

func (t *ParentTree) Rebind(key, parent Key) error

Rebind 重新链接 key 的父(同样做环检测),不要求 key 已绑定。

type ResolvedEntry

type ResolvedEntry[V any] struct {
	Name  string // 具名 key;匿名条目为空
	Value V
	Rank  int
}

ResolvedEntry 是 Merge 后的单条解析结果。

type ScopedLayers

type ScopedLayers[V any] struct {
	// contains filtered or unexported fields
}

ScopedLayers 是「host → 最近作用域」按顺序叠加的多层注册表。 层顺序:索引 0 为 host(最外层),索引越靠后作用域越近(越优先)。

func NewScopedLayers

func NewScopedLayers[V any]() *ScopedLayers[V]

NewScopedLayers 创建空的分层注册表。

func (*ScopedLayers[V]) Get

func (sl *ScopedLayers[V]) Get(name string) (V, bool)

Get 按 nearest-scope-wins 规则解析具名 key 的值。 从最近层向 host 层逐层查找,任一命中即返回;全部未命中返回 false。

func (*ScopedLayers[V]) Merge

func (sl *ScopedLayers[V]) Merge() []ResolvedEntry[V]

Merge 将所有层合并为一个确定性视图:

  • 具名条目:按 nearest-scope-wins 解析,同层内 rank/注册序决胜,输出唯一一份;
  • 匿名条目:全部保留(来自不同层、按注册顺序)。

返回值按名称字典序 + 匿名条目在前的规则排序,保证多次调用输出逐字节一致。

func (*ScopedLayers[V]) Push

func (sl *ScopedLayers[V]) Push(layer *Layer[V]) *ScopedLayers[V]

Push 追加一层作用域(追加后成为"最近的"作用域,优先于之前所有层)。 host 层应最先 Push。

Jump to

Keyboard shortcuts

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