Documentation
¶
Overview ¶
Package permission provides on-demand API permission checks for Simple Admin. It stores policies in sys_permissions instead of loading them into process memory.
Index ¶
- type Enforcer
- func MustNewWithDatabaseConf(conf config.DatabaseConf, options ...EnforcerOption) *Enforcer
- func MustNewWithDatabaseConfAndRedis(conf config.DatabaseConf, rds redis.UniversalClient, ...) *Enforcer
- func New(db *sql.DB, dialect string, options ...EnforcerOption) (*Enforcer, error)
- func NewWithDatabaseConf(conf config.DatabaseConf, options ...EnforcerOption) (*Enforcer, error)
- func NewWithDatabaseConfAndRedis(conf config.DatabaseConf, rds redis.UniversalClient, ...) (*Enforcer, error)
- func (e *Enforcer) AddPolicies(ctx context.Context, policies []Policy) (bool, error)
- func (e *Enforcer) BatchEnforce(requests [][]any) ([]bool, error)
- func (e *Enforcer) Check(ctx context.Context, subjects []string, object, action string, ...) (bool, error)
- func (e *Enforcer) Close() error
- func (e *Enforcer) InitDatabase(ctx context.Context) error
- func (e *Enforcer) ListPolicies(ctx context.Context, subject string, domains ...string) ([]Policy, error)
- func (e *Enforcer) MigrateFromCasbinRules(ctx context.Context, timeouts ...time.Duration) (migrated int64, err error)
- func (e *Enforcer) PermissionCacheStats() PermissionCacheStats
- func (e *Enforcer) RemoveDomainPolicies(ctx context.Context, domain string) (bool, error)
- func (e *Enforcer) RemovePolicies(ctx context.Context, subject string, domains ...string) (bool, error)
- func (e *Enforcer) RemovePoliciesByResources(ctx context.Context, domains []string, resources []Policy) (bool, error)
- func (e *Enforcer) RenameSubject(ctx context.Context, oldSubject, newSubject string, domains ...string) error
- func (e *Enforcer) ReplacePolicies(ctx context.Context, subject string, policies []Policy, domains ...string) error
- type EnforcerOption
- type PermissionCacheOptions
- type PermissionCacheStats
- type Policy
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Enforcer ¶
type Enforcer struct {
// contains filtered or unexported fields
}
Enforcer evaluates Simple Admin's API permission policy directly from the database. It does not keep all policies in memory and does not subscribe to policy reload notifications.
The supported matcher is the project's current matcher: r.sub == p.sub && keyMatch2(r.obj, p.obj) && r.act == p.act.
func MustNewWithDatabaseConf ¶
func MustNewWithDatabaseConf(conf config.DatabaseConf, options ...EnforcerOption) *Enforcer
MustNewWithDatabaseConf is NewWithDatabaseConf that panics on configuration or database errors, matching the existing service-context construction style.
func MustNewWithDatabaseConfAndRedis ¶
func MustNewWithDatabaseConfAndRedis(conf config.DatabaseConf, rds redis.UniversalClient, options ...PermissionCacheOptions) *Enforcer
MustNewWithDatabaseConfAndRedis is the panic-on-error variant of NewWithDatabaseConfAndRedis.
func New ¶
New creates an on-demand permission enforcer from an existing database pool. The caller owns db and is responsible for closing it. Call InitDatabase from the service's database initialization flow before serving protected routes.
func NewWithDatabaseConf ¶
func NewWithDatabaseConf(conf config.DatabaseConf, options ...EnforcerOption) (*Enforcer, error)
NewWithDatabaseConf opens a dedicated database pool for permission checks.
func NewWithDatabaseConfAndRedis ¶
func NewWithDatabaseConfAndRedis(conf config.DatabaseConf, rds redis.UniversalClient, options ...PermissionCacheOptions) (*Enforcer, error)
NewWithDatabaseConfAndRedis opens a permission database pool and enables the bounded Redis/L1 decision cache. The existing Enforcer API remains unchanged; this constructor only changes where a decision is obtained.
func (*Enforcer) AddPolicies ¶
AddPolicies adds only policies that do not already exist. Each policy must include Subject; Domain is optional for the non-tenant model.
func (*Enforcer) BatchEnforce ¶
BatchEnforce keeps the familiar Casbin method shape for gradual migrations. It accepts [subject, object, action] and [subject, object, action, domain] requests and evaluates them on demand. New middleware should prefer Check so multiple roles are queried together.
func (*Enforcer) Check ¶
func (e *Enforcer) Check(ctx context.Context, subjects []string, object, action string, domains ...string) (bool, error)
Check returns whether any subject has permission to access object with action. Static policies use the unique index (v0, v1, v2, ...). Dynamic keyMatch2 policies are only queried when the exact lookup misses. The optional domain is stored in v3. Omitting it preserves non-tenant behavior, while tenant middleware must pass its trusted tenant ID.
func (*Enforcer) Close ¶
Close closes the database pool used by this enforcer. Do not call Close when the pool passed to New is shared by another component.
func (*Enforcer) InitDatabase ¶
InitDatabase creates and indexes the permission table. It is idempotent and deliberately separate from New so permission storage is maintained by the application's database initialization flow rather than by an ORM adapter.
func (*Enforcer) ListPolicies ¶
func (e *Enforcer) ListPolicies(ctx context.Context, subject string, domains ...string) ([]Policy, error)
ListPolicies returns a role's API policies without loading the full model. The optional domain scopes the query to v3; its default is the non-tenant empty domain.
func (*Enforcer) MigrateFromCasbinRules ¶
func (e *Enforcer) MigrateFromCasbinRules(ctx context.Context, timeouts ...time.Duration) (migrated int64, err error)
MigrateFromCasbinRules creates sys_permissions and copies legacy p policies from casbin_rules only when sys_permissions did not exist before the call. An existing table is always authoritative, including an intentionally empty one, so later initialization cannot restore revoked permissions.
The legacy mapping is v0..v5 -> v0..v5. Casbin g rules and all other ptype values are ignored because Simple Admin's API authorization only uses p. An optional timeout of zero disables the migration deadline. A failed first migration removes the newly created target table so it can be retried after legacy data is corrected.
func (*Enforcer) PermissionCacheStats ¶
func (e *Enforcer) PermissionCacheStats() PermissionCacheStats
func (*Enforcer) RemoveDomainPolicies ¶
RemoveDomainPolicies removes all API permissions that belong to one domain. It is used when a tenant is disabled, reauthorized, or deleted.
func (*Enforcer) RemovePolicies ¶
func (e *Enforcer) RemovePolicies(ctx context.Context, subject string, domains ...string) (bool, error)
RemovePolicies removes one subject's API policies in one domain. It returns whether rows were removed.
func (*Enforcer) RemovePoliciesByResources ¶
func (e *Enforcer) RemovePoliciesByResources(ctx context.Context, domains []string, resources []Policy) (bool, error)
RemovePoliciesByResources removes permissions for the supplied API resources in only the specified domains, without enumerating all policies in memory.
type EnforcerOption ¶
type EnforcerOption func(*Enforcer)
EnforcerOption customizes an Enforcer without changing the existing constructor shape used by Simple Admin services.
func WithRedisCache ¶
func WithRedisCache(rds redis.UniversalClient, options ...PermissionCacheOptions) EnforcerOption
WithRedisCache enables a bounded L1 cache backed by Redis. Cache failures are fail-open to the database: authorization does not depend on Redis availability.
type PermissionCacheOptions ¶
type PermissionCacheOptions struct {
RedisTTL time.Duration
LocalTTL time.Duration
MaxLocalEntries int
KeyPrefix string
}
PermissionCacheOptions controls the optional Redis/L1 permission decision cache. RedisTTL is also the maximum cross-process staleness window.
func DefaultPermissionCacheOptions ¶
func DefaultPermissionCacheOptions() PermissionCacheOptions
DefaultPermissionCacheOptions returns conservative cache defaults for API authorization. LocalTTL can be set to zero to disable the process-local L1.
type PermissionCacheStats ¶
type PermissionCacheStats struct {
LocalHits uint64
RedisHits uint64
RedisMisses uint64
RedisErrors uint64
RedisSets uint64
}
PermissionCacheStats exposes cache behavior for diagnostics and load tests.