58 lines
1.8 KiB
Markdown
58 lines
1.8 KiB
Markdown
# ADR-0019: Permission DSL Format
|
|
|
|
## Status
|
|
Accepted
|
|
|
|
## Context
|
|
The platform needs a permission system that:
|
|
- Is extensible by modules
|
|
- Prevents typos and errors (compile-time safety)
|
|
- Supports hierarchical permissions
|
|
- Is easy to understand and use
|
|
|
|
Permission formats considered:
|
|
1. **String format**: `"module.resource.action"` - Simple, flexible
|
|
2. **Enum/Constants**: Type-safe but less flexible
|
|
3. **Hierarchical tree**: Complex but powerful
|
|
4. **Bitmask**: Efficient but hard to read
|
|
|
|
## Decision
|
|
Use **string-based permission format** with **code-generated constants**:
|
|
|
|
1. **Format**: `"{module}.{resource}.{action}"`
|
|
- Examples: `blog.post.create`, `user.read`, `system.health.check`
|
|
2. **Code generation**: Generate constants from `module.yaml` files
|
|
3. **Type safety**: `type Permission string` with generated constants
|
|
4. **Validation**: Compile-time constants prevent typos
|
|
|
|
**Rationale:**
|
|
- Simple and readable
|
|
- Easy to extend (modules define in manifest)
|
|
- Code generation provides compile-time safety
|
|
- Flexible (modules can define any format)
|
|
- Hierarchical structure is intuitive
|
|
- Easy to parse and match
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- Simple and intuitive format
|
|
- Compile-time safety via code generation
|
|
- Easy to extend by modules
|
|
- Human-readable
|
|
- Flexible for various permission models
|
|
|
|
### Negative
|
|
- String comparisons (minimal performance impact)
|
|
- Requires code generation step
|
|
- Potential for permission string conflicts (mitigated by module prefix)
|
|
|
|
### Implementation Notes
|
|
- Define `type Permission string` in `pkg/perm/perm.go`
|
|
- Create code generator: `scripts/generate-permissions.go`
|
|
- Scan `modules/*/module.yaml` for permissions
|
|
- Generate constants in `pkg/perm/generated.go`
|
|
- Use `//go:generate` directive
|
|
- Validate format: `^[a-z0-9]+(\.[a-z0-9]+)*$` (lowercase, dots)
|
|
|