mail2couch/rust/README.md

# Mail2Couch Rust Implementation

This directory contains the Rust implementation of mail2couch, which will provide the same functionality as the Go implementation while maintaining full compatibility with the CouchDB document schemas.

## Current Status

🚧 **Work in Progress** - The Rust implementation is planned for future development.

Currently available:
- ✅ **CouchDB Schema Definitions**: Complete Rust structs that match the Go implementation
- ✅ **Serialization Support**: Full serde integration for JSON handling  
- ✅ **Type Safety**: Strongly typed structures for all CouchDB documents
- ✅ **Compatibility Tests**: Validated against example documents
- ✅ **Database Naming**: Same database naming logic as Go implementation

## Schema Compatibility

The Rust implementation uses the same CouchDB document schemas as the Go implementation:

### Mail Documents
```rust
use mail2couch::{MailDocument, generate_database_name};

let mut doc = MailDocument::new(
    "123".to_string(),        // IMAP UID
    "INBOX".to_string(),      // Mailbox
    vec!["sender@example.com".to_string()],  // From
    vec!["recipient@example.com".to_string()], // To
    "Subject".to_string(),    // Subject
    Utc::now(),              // Date
    "Body content".to_string(), // Body
    HashMap::new(),          // Headers
    false,                   // Has attachments
);

doc.set_id(); // Sets ID to "INBOX_123"
```

### Sync Metadata
```rust
use mail2couch::SyncMetadata;

let metadata = SyncMetadata::new(
    "INBOX".to_string(),     // Mailbox
    Utc::now(),             // Last sync time
    456,                    // Last message UID
    100,                    // Message count
);
// ID automatically set to "sync_metadata_INBOX"
```

### Database Naming
```rust
use mail2couch::generate_database_name;

let db_name = generate_database_name("Personal Gmail", "");
// Returns: "m2c_personal_gmail"

let db_name = generate_database_name("", "user@example.com");
// Returns: "m2c_user_example_com"
```

## Dependencies

The Rust implementation uses these key dependencies:

- **serde**: JSON serialization/deserialization
- **chrono**: Date/time handling with ISO8601 support
- **reqwest**: HTTP client for CouchDB API
- **tokio**: Async runtime
- **anyhow/thiserror**: Error handling

## Testing

Run the schema compatibility tests:

```bash
cargo test
```

All tests validate that the Rust structures produce JSON compatible with the Go implementation and documented schemas.

## Future Implementation

The planned Rust implementation will include:

- **IMAP Client**: Connect to mail servers and retrieve messages
- **CouchDB Integration**: Store documents using native Rust CouchDB client
- **Configuration**: Same JSON config format as Go implementation
- **CLI Interface**: Compatible command-line interface
- **Performance**: Leveraging Rust's performance characteristics
- **Memory Safety**: Rust's ownership model for reliable operation

## Schema Documentation

See the following files for complete schema documentation:

- [`../couchdb-schemas.md`](../couchdb-schemas.md): Complete schema specification
- [`../examples/`](../examples/): JSON example documents
- [`src/schemas.rs`](src/schemas.rs): Rust type definitions

## Cross-Implementation Compatibility

Both Go and Rust implementations:
- Use identical CouchDB document schemas
- Generate the same database names
- Store documents with the same field names and types
- Support incremental sync with compatible metadata
- Handle attachments using CouchDB native attachment storage

This ensures that databases created by either implementation can be used interchangeably.