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

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

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

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:

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: Complete schema specification
• ../examples/: JSON example documents
• 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.