buster/api/prds/active/sharing_user_lookup.md

# User Lookup by Email PRD

## Overview
This PRD outlines the implementation of a user lookup functionality by email address within the sharing access controls system. This component is essential for enabling email-based sharing features.

## Background
When sharing assets with users, it's more user-friendly to use email addresses rather than user IDs. This requires a reliable way to look up users by their email addresses.

## Goals
- Implement a function to find users by email address
- Return appropriate user information needed for sharing
- Handle cases where users don't exist
- Ensure proper error handling

## Non-Goals
- Creating or modifying user records
- Implementing complex user search functionality
- Handling authentication or authorization

## Technical Design

### Component: User Lookup Module

Create a new module `user_lookup.rs` in the sharing library with the following functionality:

```rust
pub async fn find_user_by_email(email: &str) -> Result<Option<User>> {
    // Implementation details
}
```

### Implementation Details

1. The function will query the database to find a user with the given email address
2. If a user is found, return the user object
3. If no user is found, return None
4. Handle any database errors appropriately

### Database Query

The function will use the following query pattern:

```rust
users::table
    .filter(users::email.eq(email))
    .filter(users::deleted_at.is_null())
    .first::<User>(&mut conn)
    .optional()
    .await
```

### Error Handling

The function should handle the following error cases:
- Database connection errors
- Query execution errors
- Invalid email format

## Testing Strategy

### Unit Tests
- Test finding an existing user
- Test handling a non-existent user
- Test error handling for database issues

### Integration Tests
- Test the function in combination with permission creation

## Dependencies
- Database models and schema
- Diesel ORM
- Error handling utilities

## Implementation Plan
1. Create the `user_lookup.rs` file
2. Implement the `find_user_by_email` function
3. Add error handling
4. Write tests
5. Update the library exports in `lib.rs`

## Success Criteria
- Function correctly finds users by email
- Appropriate error handling is implemented
- Tests pass successfully
- Code is well-documented