Documentation
¶
Overview ¶
Package canon 提供「策略/配置面规范形指纹」原语:规范形(canonical) → schema 版本化哈希(48bit)→ 按 facet diff。任何「规则改过之后能 回答会话按哪版策略放行、两台机器授权面是否同版、按 facet 吊销受影响 面」的策略/配置治理,都复用同一条管线:配置面 → 排序/去重/缺省折算 → 版本哈希 → facet diff。stdlib-only(pkg 零第三方依赖红线)。
三条归一纪律(同语义必须同版本) ¶
「同语义必须同版本」由三条纪律钉死,前两条本包直接给原语,第三条 是宿主职责、必须在喂进 Facet 前完成:
- **排序**:集合语义字段(能力词、权限清单)声明顺序不是语义, 改一下排列不该换版本——用 SortDedup 排序后喂入;
- **去重**:同一词写两遍与写一遍是同一个能力集(去重后才是集合 语义)——同上,SortDedup 一并完成;
- **缺省折算**:{}(缺省)与显式写缺省值必须同版。缺省表是宿主 的业务语义,本包不内置:宿主用**单源折算函数**(如 admission 的 Effective)把「有效值」折算出来再喂入,禁止折算逻辑散落两处。 注意结构体显式零值与 map 缺键在 JSON 规范形里是两种形态 ("allow":false 与缺键),折算必须在喂入前完成,不能指望哈希层 兜底。
canonical 稳定性(键序无关、字段序钉死) ¶
规范形 = schema 串 + facet 名 → 值的 JSON 形态,整体一次 JSON 化:
- **map 键序无关**:encoding/json 对 map 键按字典序输出,键插入 顺序不进哈希;
- **facet 声明序无关**:facet 按 Name 字典序进规范形——清单排列 不是语义;
- **结构体字段序钉死**:结构体按字段声明序输出——字段序是规范形 的一部分。因此「改 canonical 结构」(增删字段、换字段序、改类型) 都会换哈希,**必须同时升格 Schema 串**(如 policyver/v1 → policyver/v2):版本串里的 schema 是读方识别旧形态的判据, 升格纪律是契约条文,本包按 schema 不一致的 diff 直接拒绝兜底。
48bit 的取舍 ¶
版本哈希取 sha256 前 48bit(12 个 hex 字符)。**只用于对比,不用于 防篡改**:指纹回答「这两个面是否同版」,48bit 碰撞概率在「同语义 必须同版本」的输入域下可忽略,但绝不是密码学承诺——任何把版本串当 完整性证明的用法都是错的(防篡改请用完整 sha256 或签名)。
宿主既有规范形字节(迁移接缝) ¶
已上线宿主往往已经持久化了历史版本指纹,且其规范形字节布局与本包的 canonicalDoc 不同。强制切到 Fingerprint 会让存量快照全部失配(一夜 之间被判「策略已变」)。FingerprintBytes 把「规范化」与「指纹」解耦: 宿主继续按历史布局自产规范形字节,canon 只做 sha256 + 48bit 版本串 格式化,历史 12-hex 值可原样复算。schema 参数只是版本串前缀,不参与 哈希;同一份字节换 schema 标签不换摘要。需要与 Fingerprint 并存时, 两条入口的摘要口径一致(同字节同值),差异只在「schema 是否进规范形」。
facet diff ¶
Diff 按 facet 名逐片比较各自规范形指纹,产出 Added/Changed/Removed 清单(同版 facet 不报)。按 facet 吊销受影响面(会话按旧版放行的 记录、mandate 重检)直接消费这份清单;FacetDigest 可独立持久化 单个 facet 的指纹(会话行记 policy_version + 命中 facet 集)。 DiffDigests 是同一比较口径的「已持久化指纹」入口:宿主只有两代 facet 指纹 map、重建不出 Surface 时直接消费它,顺序与 Diff 一致 (Added→Changed→Removed,各段按 facet 名排序)。
用法 ¶
surface := canon.Surface{
Schema: "policyver/v1", // 宿主自己的 schema 命名空间
Facets: []canon.Facet{
{Name: "role:admin", Value: canon.SortDedup(conf.AdminWords)},
{Name: "admission", Value: admission.Effective(conf.Admission)},
},
}
ver, err := canon.Fingerprint(surface) // "policyver/v1:3f9a1c2b4d5e"
changes, err := canon.Diff(oldSurface, surface)
for _, ch := range changes { // 按 facet 吊销受影响面
revokeFacet(ch.Name, ch.Kind)
}
Index ¶
Constants ¶
const DefaultSchema = "canon/v1"
DefaultSchema 缺省 schema 版本串(宿主可经 Surface.Schema 覆盖为 自己的命名空间,如 "policyver/v1")。
Variables ¶
var ( ErrBadSurface = errors.New("canon: surface 非法") ErrUnencodable = errors.New("canon: facet 值不可 JSON 化") ErrSchemaMismatch = errors.New("canon: 新旧快照 schema 不一致,不可 diff") )
哨兵错误:errors.Is 可判定(非法入参归 ErrBadSurface / ErrUnencodable / ErrSchemaMismatch,文案带上下文)。
Functions ¶
func FacetDigest ¶
FacetDigest 单个 facet 值的规范形指纹(48bit 十六进制):按 facet 吊销/ 比对时可独立持久化的切片指纹,与会话行记的 policy_version 配套。 名字不进切片指纹——切片指纹只对「值」负责,名字是装配层的键。
Types ¶
type Change ¶
type Change struct {
Kind ChangeKind
Name string
From string // 旧指纹(Removed/Changed 时非空)
To string // 新指纹(Added/Changed 时非空)
}
Change 一个 facet 的变更记录。
func Diff ¶
Diff 按 facet 名逐片比较两个快照,返回变更清单。确定性顺序:Added 在前、Changed 居中、Removed 在后,各段按 Name 字典序——「新面多了 什么、什么变了、什么没了」。同版 facet 不报。新旧 schema 不一致按 ErrSchemaMismatch 拒绝:跨 schema 的 diff 是无意义比对,升格纪律 在此兜底。比较本体复用 DiffDigests(两条入口同口径)。
func DiffDigests ¶ added in v0.51.0
DiffDigests 直接比较两代 facet 指纹(map[facet 名]digest,宿主已持久化 的 FacetDigest 产物),返回与 Diff 同口径的变更清单:确定性顺序 Added 在前、Changed 居中、Removed 在后,各段按 Name 字典序;同指纹不报。 nil/空 map 合法(该代没有 facet)。
适用面:宿主只存了上一代指纹、重建不出 Surface 的场景(会话行记 policy_version + facet 指纹集)。本函数拿不到 schema,因此无法像 Diff 那样兜底 ErrSchemaMismatch——调用方必须保证两代指纹来自同一 schema,跨 schema 的指纹 map 不可比。
type ChangeKind ¶
type ChangeKind int
ChangeKind facet 变更形态。
const ( FacetAdded ChangeKind = iota // 新面新增的 facet FacetChanged // 两面同名但指纹不同 FacetRemoved // 旧面有、新面没有 )
type Facet ¶
Facet 策略面的一个可独立比对/吊销的切片。Name 在快照内唯一; Value 是宿主**已完成三条归一纪律**(排序/去重/缺省折算,见包文档) 的结构,须可 JSON 化(map 键序无关、结构体字段序钉死)。
type Surface ¶
Surface 一次策略面快照。Schema 空 = DefaultSchema;改 canonical 结构必须升格 Schema 串(契约见包文档「canonical 稳定性」)。
type Version ¶
Version 版本指纹:schema 前缀 + 48bit 十六进制摘要。
func Fingerprint ¶
Fingerprint 计算快照的版本指纹:规范形 JSON → sha256 → 48bit 十六进制。 同语义(三条归一纪律后)必同版、可复现。哈希与版本格式化复用 FingerprintBytes,两条入口不会漂移出两套摘要口径。
func FingerprintBytes ¶ added in v0.51.0
FingerprintBytes 对宿主自产的规范形字节计算版本指纹:canon 只负责 哈希与版本串格式化,**不再规范化**——字节里有没有 schema 字段、字段 怎么排序,全由宿主历史布局决定(sha256 原样吃入,不 trim、不补空)。
这是「规范化」与「指纹」解耦的迁移接缝:已持久化历史版本指纹的宿主 保持原布局产出字节,即可用本函数原样复算历史值(12 个 hex 字符), 不必为了收编 canon 而让存量快照全部失配。
schema 只是版本串前缀,不参与哈希(这一点与 Fingerprint 不同: 后者的 schema 写在规范形 JSON 里,升格会换哈希);空 schema 回退 DefaultSchema。空 nil 字节按 ErrBadSurface 拒绝(空面无版本可言)。