Documentation
¶
Overview ¶
Package registry contains interfaces and default implementations for the custom role registry. Default structs compose go-repository-bun repositories but can be replaced by the host application via dependency injection.
Index ¶
- Variables
- func CustomRoleToDefinition(record *CustomRole) *types.RoleDefinition
- type CustomRole
- type RoleAssignment
- type RoleRegistry
- func (r *RoleRegistry) AssignRole(ctx context.Context, userID, roleID uuid.UUID, scope types.ScopeFilter, ...) error
- func (r *RoleRegistry) AssignRoleFromCatalog(ctx context.Context, grant types.ScopedRoleGrant) error
- func (r *RoleRegistry) BindTx(tx bun.Tx) *RoleRegistry
- func (r *RoleRegistry) CreateRole(ctx context.Context, input types.RoleMutation) (*types.RoleDefinition, error)
- func (r *RoleRegistry) DeleteRole(ctx context.Context, id uuid.UUID, scope types.ScopeFilter, actor uuid.UUID) error
- func (r *RoleRegistry) GetRole(ctx context.Context, id uuid.UUID, scope types.ScopeFilter) (*types.RoleDefinition, error)
- func (r *RoleRegistry) ListAssignments(ctx context.Context, filter types.RoleAssignmentFilter) ([]types.RoleAssignment, error)
- func (r *RoleRegistry) ListRoles(ctx context.Context, filter types.RoleFilter) (types.RolePage, error)
- func (r *RoleRegistry) UnassignRole(ctx context.Context, userID, roleID uuid.UUID, scope types.ScopeFilter, ...) error
- func (r *RoleRegistry) UpdateRole(ctx context.Context, id uuid.UUID, input types.RoleMutation) (*types.RoleDefinition, error)
- func (r *RoleRegistry) WithTx(tx bun.Tx) (*RoleRegistry, error)
- type RoleRegistryConfig
Constants ¶
This section is empty.
Variables ¶
var ErrUnsupportedRoleScope = errors.New("bun role registry: role definitions do not support scope labels")
ErrUnsupportedRoleScope indicates that a custom label was supplied to a role catalog operation. Definitions use tenant/org namespaces; labels belong on assignments to those definitions.
Functions ¶
func CustomRoleToDefinition ¶
func CustomRoleToDefinition(record *CustomRole) *types.RoleDefinition
CustomRoleToDefinition exposes the conversion logic for consumers that need to translate Bun models into domain role definitions.
Types ¶
type CustomRole ¶
type CustomRole struct {
bun.BaseModel `bun:"table:custom_roles"`
ID uuid.UUID `bun:",pk,type:uuid"`
Name string `bun:"name,notnull"`
Order int `bun:"order,notnull,default:0"`
Description string `bun:"description"`
RoleKey string `bun:"role_key"`
Permissions []string `bun:"permissions,type:jsonb"`
Metadata map[string]any `bun:"metadata,type:jsonb"`
IsSystem bool `bun:"is_system,notnull"`
TenantID uuid.UUID `bun:"tenant_id,type:uuid,notnull,default:'00000000-0000-0000-0000-000000000000'"`
OrgID uuid.UUID `bun:"org_id,type:uuid,notnull,default:'00000000-0000-0000-0000-000000000000'"`
CreatedAt time.Time `bun:"created_at,notnull"`
UpdatedAt time.Time `bun:"updated_at,notnull"`
CreatedBy uuid.UUID `bun:"created_by,type:uuid,notnull"`
UpdatedBy uuid.UUID `bun:"updated_by,type:uuid,notnull"`
}
CustomRole represents the schema stored in custom_roles.
func DefinitionToCustomRole ¶
func DefinitionToCustomRole(definition *types.RoleDefinition) *CustomRole
DefinitionToCustomRole converts a domain role definition into the Bun model.
type RoleAssignment ¶
type RoleAssignment struct {
bun.BaseModel `bun:"table:user_custom_roles"`
UserID uuid.UUID `bun:"user_id,type:uuid,pk"`
RoleID uuid.UUID `bun:"role_id,type:uuid,pk"`
TenantID uuid.UUID `bun:"tenant_id,type:uuid,pk"`
OrgID uuid.UUID `bun:"org_id,type:uuid,pk"`
ScopeKey string `bun:"scope_key,pk,notnull"`
Labels map[string]uuid.UUID `bun:"labels,type:jsonb,notnull"`
AssignedAt time.Time `bun:"assigned_at,notnull"`
AssignedBy uuid.UUID `bun:"assigned_by,type:uuid,notnull"`
}
RoleAssignment represents rows from user_custom_roles.
type RoleRegistry ¶
type RoleRegistry struct {
// contains filtered or unexported fields
}
RoleRegistry persists custom roles and assignments using Bun repositories.
func NewRoleRegistry ¶
func NewRoleRegistry(cfg RoleRegistryConfig) (*RoleRegistry, error)
NewRoleRegistry constructs the default registry. Either DB or both repositories must be provided; when DB is supplied the repositories are created automatically.
func (*RoleRegistry) AssignRole ¶
func (r *RoleRegistry) AssignRole(ctx context.Context, userID, roleID uuid.UUID, scope types.ScopeFilter, actor uuid.UUID) error
AssignRole creates a user->role assignment scoped to tenant/org and exact labels.
func (*RoleRegistry) AssignRoleFromCatalog ¶ added in v0.27.0
func (r *RoleRegistry) AssignRoleFromCatalog(ctx context.Context, grant types.ScopedRoleGrant) error
AssignRoleFromCatalog reuses a catalog definition in an independent exact scope.
func (*RoleRegistry) BindTx ¶ added in v0.27.0
func (r *RoleRegistry) BindTx(tx bun.Tx) *RoleRegistry
BindTx is the native Group adapter for WithTx. It returns nil for an invalid receiver/transaction; callers needing a configuration error should use WithTx. It retains WithTx's transaction ordering and suppressed-hook contract.
func (*RoleRegistry) CreateRole ¶
func (r *RoleRegistry) CreateRole(ctx context.Context, input types.RoleMutation) (*types.RoleDefinition, error)
CreateRole inserts a custom role scoped to the provided tenant/org.
func (*RoleRegistry) DeleteRole ¶
func (r *RoleRegistry) DeleteRole(ctx context.Context, id uuid.UUID, scope types.ScopeFilter, actor uuid.UUID) error
DeleteRole removes a custom role (unless marked as system).
func (*RoleRegistry) GetRole ¶
func (r *RoleRegistry) GetRole(ctx context.Context, id uuid.UUID, scope types.ScopeFilter) (*types.RoleDefinition, error)
GetRole returns a single role matching the scope constraints.
func (*RoleRegistry) ListAssignments ¶
func (r *RoleRegistry) ListAssignments(ctx context.Context, filter types.RoleAssignmentFilter) ([]types.RoleAssignment, error)
ListAssignments returns assignments filtered by scope/user/role.
func (*RoleRegistry) ListRoles ¶
func (r *RoleRegistry) ListRoles(ctx context.Context, filter types.RoleFilter) (types.RolePage, error)
ListRoles returns paginated roles filtered by scope/keyword.
func (*RoleRegistry) UnassignRole ¶
func (r *RoleRegistry) UnassignRole(ctx context.Context, userID, roleID uuid.UUID, scope types.ScopeFilter, actor uuid.UUID) error
UnassignRole removes an existing user->role assignment.
func (*RoleRegistry) UpdateRole ¶
func (r *RoleRegistry) UpdateRole(ctx context.Context, id uuid.UUID, input types.RoleMutation) (*types.RoleDefinition, error)
UpdateRole updates mutable fields on a custom role.
func (*RoleRegistry) WithTx ¶ added in v0.27.0
func (r *RoleRegistry) WithTx(tx bun.Tx) (*RoleRegistry, error)
WithTx returns an independent registry whose catalog and assignment operations use the caller's transaction. It neither commits nor rolls back. The caller must lock authoritative authorization state before checks, and must use this same transaction for policy reads, version advancement and required audit. The transaction must belong to the repositories' database. Transaction-scoped registries must not escape the callback or be used concurrently.
Hooks are suppressed: a database write is not yet a committed event. Persist required publication in an outbox in the same transaction, then deliver after commit. The original registry and its hooks remain unchanged.
type RoleRegistryConfig ¶
type RoleRegistryConfig struct {
DB *bun.DB
Roles repository.Repository[*CustomRole]
Assignments repository.Repository[*RoleAssignment]
Clock types.Clock
Hooks types.Hooks
Logger types.Logger
IDGenerator types.IDGenerator
}
RoleRegistryConfig configures the Bun-backed role registry.