permission

package
v1.8.8 Latest Latest
Warning

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

Go to latest
Published: Sep 5, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

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

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

func New(db *sql.DB, dialect string, options ...EnforcerOption) (*Enforcer, error)

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

func (e *Enforcer) AddPolicies(ctx context.Context, policies []Policy) (bool, error)

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

func (e *Enforcer) BatchEnforce(requests [][]any) ([]bool, error)

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

func (e *Enforcer) Close() error

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

func (e *Enforcer) InitDatabase(ctx context.Context) error

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

func (e *Enforcer) RemoveDomainPolicies(ctx context.Context, domain string) (bool, error)

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.

func (*Enforcer) RenameSubject

func (e *Enforcer) RenameSubject(ctx context.Context, oldSubject, newSubject string, domains ...string) error

RenameSubject keeps policies consistent after a role code changes. The optional domain prevents identical role codes in other tenants being renamed.

func (*Enforcer) ReplacePolicies

func (e *Enforcer) ReplacePolicies(ctx context.Context, subject string, policies []Policy, domains ...string) error

ReplacePolicies atomically replaces one subject's API policies in one domain. Omitting the optional domain preserves the non-tenant v3 = ” behavior.

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.

type Policy

type Policy struct {
	Subject string
	Object  string
	Action  string
	Domain  string
}

Policy is the API permission row stored in sys_permissions. Its field mapping deliberately preserves the legacy layout: Subject -> v0, Object -> v1, Action -> v2 and Domain -> v3. v4 and v5 remain reserved for future use.

Jump to

Keyboard shortcuts

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