buster/api/prds/active/api_chat_handlers_refactor.md

# Chat Handlers Authentication Refactor

## Overview
This PRD outlines the plan to refactor all chat handlers in `libs/handlers/src/chats/` to accept the complete `AuthenticatedUser` object instead of just the `user_id` parameter.

## Problem Statement
Currently, chat handlers accept only a user ID (`Uuid`) as the user parameter. This approach has several limitations:

1. It lacks rich user context information such as organization memberships and roles
2. It requires additional database lookups to fetch user attributes
3. It doesn't align with the REST endpoints which already use the `AuthenticatedUser` type from middleware

By refactoring these handlers to accept the complete `AuthenticatedUser` object, we will:
- Improve code efficiency by reducing redundant database queries
- Enhance security by making permission checks more comprehensive
- Increase consistency across the codebase
- Improve test reliability with standardized test user fixtures

## Goals
- Update all chat handlers to use `AuthenticatedUser` instead of user ID
- Optimize handler code to use available user context information
- Ensure tests continue to pass with the new parameter format
- Maintain or improve existing functionality

## Non-Goals
- Changing the business logic of the chat handlers
- Modifying the database schema
- Adding new features to chat handlers
- Changing the API contract between handlers and consumers

## Technical Design

### Overview
The refactoring will involve updating function signatures across all chat handlers to accept `&AuthenticatedUser` instead of `&Uuid`, and then modifying the internal logic to use `user.id` instead of `user_id` where appropriate. We'll also leverage additional user information to optimize certain operations.

### Components to Modify

#### Chat Handlers
1. `get_chat_handler.rs`
2. `list_chats_handler.rs`
3. `update_chats_handler.rs`
4. `delete_chats_handler.rs`
5. `post_chat_handler.rs` 
6. `get_raw_llm_messages_handler.rs`

#### Chat Sharing Handlers
1. `sharing/create_sharing_handler.rs`
2. `sharing/list_sharing_handler.rs`
3. `sharing/update_sharing_handler.rs`
4. `sharing/delete_sharing_handler.rs`

#### Example Function Signature Changes

```rust
// Before
pub async fn get_chat_handler(chat_id: &Uuid, user_id: &Uuid) -> Result<ChatWithMessages> {
    // ...
}

// After
pub async fn get_chat_handler(chat_id: &Uuid, user: &AuthenticatedUser) -> Result<ChatWithMessages> {
    // ...
}
```

#### Code Changes Pattern

For each handler, we'll:
1. Update the function signature to accept `&AuthenticatedUser` instead of `&Uuid`
2. Replace all instances of `user_id` with `user.id` in function body
3. Leverage user attributes where applicable (like `user.avatar_url` or organization info)
4. Update database queries to filter by `user.id` instead of `user_id`

#### Example Implementation (for get_chat_handler.rs)

```rust
// Before
pub async fn get_chat_handler(chat_id: &Uuid, user_id: &Uuid) -> Result<ChatWithMessages> {
    // Run thread and messages queries concurrently
    let thread_future = {
        // ...
        tokio::spawn(async move {
            chats::table
                // ...
                .filter(chats::created_by.eq(user_id))
                // ...
        })
    };
    // ...
}

// After
pub async fn get_chat_handler(chat_id: &Uuid, user: &AuthenticatedUser) -> Result<ChatWithMessages> {
    // Run thread and messages queries concurrently
    let thread_future = {
        // ...
        let user_id = user.id;
        tokio::spawn(async move {
            chats::table
                // ...
                .filter(chats::created_by.eq(user_id))
                // ...
        })
    };
    // ...
    
    // We can now use user.avatar_url directly instead of extracting it from the database
    // This optimization is possible because we have the full user object
}
```

### Performance Optimizations

The refactoring will allow for several optimizations:

1. **Avoid User Lookups**: We can directly use user data from the `AuthenticatedUser` object instead of querying the database
2. **Organization Context**: We can use organization memberships for permission checks without additional queries
3. **Team Context**: We can use team memberships for enhanced authorization

### REST Endpoint Changes

REST endpoints will need minimal changes:

```rust
// Before
pub async fn get_chat_route(
    Path(chat_id): Path<Uuid>,
    Extension(user): Extension<AuthenticatedUser>
) -> Result<ApiResponse<ChatWithMessages>, ApiError> {
    let result = get_chat_handler(&chat_id, &user.id).await?;
    // ...
}

// After 
pub async fn get_chat_route(
    Path(chat_id): Path<Uuid>,
    Extension(user): Extension<AuthenticatedUser>
) -> Result<ApiResponse<ChatWithMessages>, ApiError> {
    let result = get_chat_handler(&chat_id, &user).await?;
    // ...
}
```

### Files to Modify

#### Handler Files
1. `/libs/handlers/src/chats/get_chat_handler.rs`
2. `/libs/handlers/src/chats/list_chats_handler.rs`
3. `/libs/handlers/src/chats/update_chats_handler.rs`
4. `/libs/handlers/src/chats/delete_chats_handler.rs`
5. `/libs/handlers/src/chats/post_chat_handler.rs`
6. `/libs/handlers/src/chats/get_raw_llm_messages_handler.rs`
7. `/libs/handlers/src/chats/sharing/create_sharing_handler.rs`
8. `/libs/handlers/src/chats/sharing/list_sharing_handler.rs`
9. `/libs/handlers/src/chats/sharing/update_sharing_handler.rs`
10. `/libs/handlers/src/chats/sharing/delete_sharing_handler.rs`

#### REST Endpoints
1. `/src/routes/rest/routes/chats/get_chat.rs`
2. `/src/routes/rest/routes/chats/list_chats.rs`
3. `/src/routes/rest/routes/chats/update_chat.rs`
4. `/src/routes/rest/routes/chats/update_chats.rs`
5. `/src/routes/rest/routes/chats/delete_chats.rs`
6. `/src/routes/rest/routes/chats/post_chat.rs`
7. `/src/routes/rest/routes/chats/get_chat_raw_llm_messages.rs`
8. `/src/routes/rest/routes/chats/sharing/create_sharing.rs`
9. `/src/routes/rest/routes/chats/sharing/list_sharing.rs`
10. `/src/routes/rest/routes/chats/sharing/update_sharing.rs`
11. `/src/routes/rest/routes/chats/sharing/delete_sharing.rs`

#### Tests (if they exist)
1. Any test files that directly call these chat handlers

## Implementation Plan

### Phase 1: Function Signatures
- ⏳ Update all chat handler function signatures
- ⏳ Adjust internal references to use `user.id` instead of `user_id`
- 🔜 Run initial tests to identify any immediate issues

### Phase 2: Functionality Updates
- 🔜 Optimize handlers to use `AuthenticatedUser` properties where applicable
- 🔜 Update any permission or filtering logic to leverage user roles
- 🔜 Implement comprehensive testing for all refactored handlers

### Phase 3: REST Endpoint Integration
- 🔜 Update all chat-related REST endpoints to pass the full user object
- 🔜 Run integration tests to ensure everything works together
- 🔜 Fix any issues that emerge during testing

### Phase 4: Documentation and Cleanup
- 🔜 Update function documentation to reflect new parameter
- 🔜 Clean up any legacy code related to user lookups
- 🔜 Finalize test suite for the refactored handlers

## Testing Strategy

### Unit Tests
- Each refactored handler will need unit tests with the new parameter
- Tests will need to use the new test utilities to create mock users
- Tests should verify handling of different user roles and permissions

### Integration Tests
- REST endpoints need to be tested to verify they properly pass the user object
- End-to-end flow tests to ensure everything works together
- Performance testing to confirm optimizations provide expected benefits

### Test Cases
1. User retrieving their own chat
2. User attempting to access a chat they don't own or have permission for
3. Admin user accessing another user's chat
4. Bulk operations with different user types
5. Handling of sharing operations with different permission levels

## Rollback Plan
If issues arise during implementation:
1. Revert affected handlers to accept both formats temporarily
2. Implement wrapper functions until issues are resolved
3. Roll back specific problematic handlers if necessary

## Success Criteria
- All chat handlers accept `AuthenticatedUser` instead of just user ID
- All tests pass with the new implementation
- REST endpoints work correctly with refactored handlers
- No regression in functionality or performance
- Improved code maintainability and reduced redundant database queries

## Dependencies
- Completion of the test utilities for creating mock `AuthenticatedUser` objects
- `middleware::AuthenticatedUser` struct from `libs/middleware/src/types.rs`
- Existing chat handlers implementation

## Timeline
Expected completion time: 1 week

This PRD depends on the completion of the test utilities PRD and should be implemented after that work is done.