scoper

package
v0.12.2 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package scoper 提供行级数据可见性规则的单源插件(#102):同一份规则定义 同时驱动 SQL WHERE 面(GORM scope)与内存判定面(CheckScope 形态), 消除「SQL 侧手搓 WHERE 变体 + 服务层 if 同规则两处维护」的双轨漂移面 ——规则改动要两处同步、SQL 侧列名字符串拼接无类型保护、拼错编译期不可发现。

规则形态覆盖消费方实证的「admin 全量 / 其余仅本人 + 内置行可见」矩阵:

rule := scoper.NewRule[Task]("uid", func(t Task) int64 { return t.UID },
    scoper.WithBuiltinRows("is_builtin", true, func(t Task) bool { return t.Builtin }))

// SQL 面:与既有仓储形态共存(Scopes 非侵入)
db.Scopes(rule.Scope(scoper.Subject{UID: uid, Admin: isAdmin})).Find(&items)

// 内存面:同一份规则求值(服务层 CheckScope 的单源替身)
if !rule.Allows(item, scoper.Subject{UID: uid, Admin: isAdmin}) { ... }

与两轨现状的关系

消费方此前的三变体(ApplyScope / ApplyScopeOrBuiltin / ApplyScopeWithSystem) 在这里是同一 Rule 的两种配置:不配 WithBuiltinRows = 仅本人;配上 = 本人 OR 内置行。admin 旁路在 Subject 上显式声明(role→admin 的解释属调用方)。

fail-closed 契约

规则未配置完整(ownerColumn 空 / ownerOf nil;配置了 WithBuiltinRows 时 column 空 / match nil,#195)时:SQL 面注入恒假 1=0、内存面恒 false—— 可见性规则缺失时宁可全不可见,绝不无过滤放行(与 crud 包 Query 的 fail-closed 同一纪律)。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Rule

type Rule[T any] struct {
	// contains filtered or unexported fields
}

Rule[T] 是行级可见性规则的单源定义:admin 全量 / 其余仅本人, 可选内置行(如系统预置数据)对所有人可见。不可变,构造后可并发共享。

func NewRule

func NewRule[T any](ownerColumn string, ownerOf func(T) int64, opts ...RuleOption[T]) *Rule[T]

NewRule 创建行级可见性规则。ownerColumn 是行所有者的**数据库列名** (SQL WHERE 侧直接使用,禁止拼入用户输入);ownerOf 从实体取所有者标识 (内存面),两者必须指向同一语义列。

func (*Rule[T]) Allows

func (r *Rule[T]) Allows(row T, sub Subject) bool

Allows 是内存面判定:与 Scope 完全同一规则求值。

Admin ⇒ true;ownerOf(row) == sub.UID ⇒ true;
配置了内置行且 match(row) ⇒ true;其余 false。

规则缺失时恒 false(fail-closed,与 Scope 的 1=0 对偶)。

func (*Rule[T]) Scope

func (r *Rule[T]) Scope(sub Subject) func(db *gorm.DB) *gorm.DB

Scope 返回 SQL 面的 GORM scope 函数:

  • Admin:恒等 scope(全量,不过滤);
  • 规则缺失:注入恒假 1=0(fail-closed,绝不无过滤放行);
  • 其余:WHERE owner = uid(配置了内置行时为 owner = uid OR col = val)。

返回的 scope 无共享可变状态,可复用、可并发。

type RuleOption

type RuleOption[T any] func(*Rule[T])

RuleOption 配置 Rule 的行为(函数选项模式;不裸用 Option 之名, 避免多包 co-import 冲突)。

func WithBuiltinRows

func WithBuiltinRows[T any](column string, value any, match func(T) bool) RuleOption[T]

WithBuiltinRows 声明内置行可见:非 admin 主体除本人行外还可见 `<column> = <value>` 的行(SQL 面 owner = ? OR column = value; 内存面 ownerOf(row) == uid 或 match(row))。column 禁止拼入用户输入。

column 为空或 match 为 nil 属非法配置:规则**整体**走 fail-closed (SQL 面恒假 1=0、内存面恒 false,#195)——此前不在完整性判定里, match nil 在 Allows 内存面 nil func call 直接 panic、column 空在 Scope SQL 面拼出非法 SQL(500),都不是声明的 fail-closed 形态。

type Subject

type Subject struct {
	// UID 行所有者标识(与 Rule 的 OwnerColumn 同域)。
	UID int64
	// Admin 管理员旁路:true 时全量可见(SQL 面恒等 scope / 内存面恒 true)。
	Admin bool
}

Subject 是一次可见性判定的主体。

Jump to

Keyboard shortcuts

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