49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
---
|
|
sessionId: session-260725-084752-m7a6
|
|
---
|
|
|
|
# Requirements
|
|
|
|
### Overview & Goals
|
|
The goal is to design `RequireServerPermission<const P: u64>` and `RequireChannelPermission<const P: u64>` Axum extractors using const generics with bitflags, and provide clear documentation and usage examples for developers adding permissions to view handlers.
|
|
|
|
### Scope
|
|
- **In Scope:**
|
|
- Designing `RequireServerPermission<const PERM: u64>` and `RequireChannelPermission<const PERM: u64>` using const generics with `ServerPermission` and `ChannelPermission` bitflags.
|
|
- Designing the path parameter extraction strategy for scope (extracting `server_id` or `channel_id` from request extensions / path parameters).
|
|
- Handling superuser bypass (`is_superuser`) automatically.
|
|
- Adding detailed documentation and usage examples (`src/http/permissions.rs` doc comments / guide).
|
|
- **Out of Scope:**
|
|
- Modifying existing view handlers or database/repository schemas.
|
|
|
|
### Functional Requirements
|
|
- **FR1:** The extractor must support const generic bitflags.
|
|
- **FR2:** The extractor must automatically extract `CurrentUser`, check `is_superuser` for bypass, and fetch the required scope (`server_id` or `channel_id`).
|
|
- **FR3:** Unauthorized requests are rejected with `403 Forbidden`, unauthenticated with `401 Unauthorized`.
|
|
|
|
# Technical Design
|
|
|
|
### Current Implementation
|
|
- `CurrentUser` and `Superuser` extractors in `src/http/context.rs` implement `FromRequestParts`.
|
|
- `ServerPermission` and `ChannelPermission` are defined as `bitflags!` in `src/permissions.rs`.
|
|
|
|
### Key Decisions
|
|
- **Decision 1: Const Generics for Permission Extractors**
|
|
- *Choice:* Use `RequireServerPermission<const PERM: u64>` and `RequireChannelPermission<const PERM: u64>`.
|
|
- *Rationale:* Allows clean, declarative handler annotations.
|
|
- **Decision 2: Providing the Scope (`server_id` / `channel_id`)**
|
|
- *Choice:* Extract path parameters (`server_id` / `channel_id` / `id`) dynamically via Axum path parameters / extensions.
|
|
|
|
### Proposed Changes
|
|
1. **Implement `src/http/permissions.rs`:**
|
|
- Define `RequireServerPermission<const PERM: u64>` and `RequireChannelPermission<const PERM: u64>`.
|
|
- Implement `FromRequestParts`.
|
|
- Add extensive inline documentation and code examples showing how to annotate route handlers with `RequireServerPermission::<{ ServerPermission::MANAGE_SERVER.bits() }>` and `RequireChannelPermission::<{ ChannelPermission::READ_CHANNEL.bits() }>`.
|
|
|
|
### File Structure Changes
|
|
- **New File:** `src/http/permissions.rs`
|
|
|
|
# Testing
|
|
|
|
### Validation Approach
|
|
- Write unit/mock tests for the permission extractors. |