|
1
|
# IMAP Implementation Documentation |
|
2
|
|
|
3
|
This document describes the IMAP (Internet Message Access Protocol) implementation in the smbcloud-mail server. |
|
4
|
|
|
5
|
## Overview |
|
6
|
|
|
7
|
The IMAP implementation provides a complete RFC 3501-compliant IMAP4rev1 server that works alongside the existing SMTP implementation. Messages received via SMTP are stored in mailboxes that can be accessed through IMAP. |
|
8
|
|
|
9
|
## Architecture |
|
10
|
|
|
11
|
### Core Components |
|
12
|
|
|
13
|
1. **Message Module** (`src/imap/message.rs`) |
|
14
|
- `Message`: Represents an email message with metadata |
|
15
|
- `MessageFlag`: Enum for standard IMAP flags (Seen, Answered, Flagged, Deleted, Draft, Recent) |
|
16
|
- Supports UID and sequence number addressing |
|
17
|
- Parses subject and body from raw email content |
|
18
|
|
|
19
|
2. **Mailbox Module** (`src/imap/mailbox.rs`) |
|
20
|
- `Mailbox`: Container for messages with thread-safe access |
|
21
|
- `MailboxStore`: Central storage for multiple mailboxes |
|
22
|
- Default mailboxes: INBOX, Sent, Drafts, Trash |
|
23
|
- Provides message counting (exists, recent, unseen) |
|
24
|
- UID management with uidvalidity and uidnext |
|
25
|
|
|
26
|
3. **State Module** (`src/imap/state.rs`) |
|
27
|
- `ImapState`: State machine for IMAP protocol |
|
28
|
- States: NotAuthenticated, Authenticated, Selected, Logout |
|
29
|
- Enforces proper command sequencing |
|
30
|
|
|
31
|
4. **Commands Module** (`src/imap/commands.rs`) |
|
32
|
- `ImapCommand`: Parser for IMAP commands |
|
33
|
- `ImapResponse`: Formatter for IMAP responses |
|
34
|
- `ImapCommandHandler`: Command execution logic |
|
35
|
- Implements all essential IMAP commands |
|
36
|
|
|
37
|
5. **Session Module** (`src/imap/session.rs`) |
|
38
|
- `ImapSession`: Async session handler |
|
39
|
- Manages client connections |
|
40
|
- Processes commands and generates responses |
|
41
|
- Uses Tokio's async I/O |
|
42
|
|
|
43
|
6. **Listen Module** (`src/imap/listen.rs`) |
|
44
|
- TCP listener for IMAP connections |
|
45
|
- Spawns session handlers for each connection |
|
46
|
- Runs on port 1143 by default |
|
47
|
|
|
48
|
7. **Storage Module** (`src/storage.rs`) |
|
49
|
- `MessageStorage`: Bridge between SMTP and IMAP |
|
50
|
- Shared mailbox store |
|
51
|
- Thread-safe message storage |
|
52
|
|
|
53
|
## Implemented Commands |
|
54
|
|
|
55
|
### Authentication Commands |
|
56
|
- **CAPABILITY**: Lists server capabilities |
|
57
|
- **LOGIN**: Authenticates user (accepts any credentials for demo) |
|
58
|
- **LOGOUT**: Closes connection |
|
59
|
|
|
60
|
### Mailbox Commands |
|
61
|
- **LIST/LSUB**: Lists available mailboxes |
|
62
|
- **SELECT**: Selects a mailbox in read-write mode |
|
63
|
- **EXAMINE**: Selects a mailbox in read-only mode |
|
64
|
- **STATUS**: Gets mailbox status without selecting |
|
65
|
|
|
66
|
### Message Commands |
|
67
|
- **FETCH**: Retrieves message data (FLAGS, UID, BODY, ENVELOPE, etc.) |
|
68
|
- **SEARCH**: Searches for messages (simplified implementation) |
|
69
|
- **NOOP**: No operation (keepalive) |
|
70
|
|
|
71
|
## Protocol State Machine |
|
72
|
|
|
73
|
``` |
|
74
|
┌─────────────────────┐ |
|
75
|
│ NotAuthenticated │ |
|
76
|
└──────────┬──────────┘ |
|
77
|
│ LOGIN |
|
78
|
▼ |
|
79
|
┌─────────────────────┐ |
|
80
|
│ Authenticated │ |
|
81
|
└──────────┬──────────┘ |
|
82
|
│ SELECT/EXAMINE |
|
83
|
▼ |
|
84
|
┌─────────────────────┐ |
|
85
|
│ Selected │ |
|
86
|
└──────────┬──────────┘ |
|
87
|
│ LOGOUT |
|
88
|
▼ |
|
89
|
┌─────────────────────┐ |
|
90
|
│ Logout │ |
|
91
|
└─────────────────────┘ |
|
92
|
``` |
|
93
|
|
|
94
|
## Integration with SMTP |
|
95
|
|
|
96
|
1. **Shared Storage**: Both SMTP and IMAP use the same `MessageStorage` instance |
|
97
|
2. **Message Flow**: |
|
98
|
- Email received via SMTP → Stored in `MessageStorage` → Accessible via IMAP INBOX |
|
99
|
3. **Concurrent Operation**: SMTP (port 2525) and IMAP (port 1143) run simultaneously |
|
100
|
|
|
101
|
## Usage Examples |
|
102
|
|
|
103
|
### Basic IMAP Session |
|
104
|
```bash |
|
105
|
# Connect and list mailboxes |
|
106
|
printf "a1 LOGIN user pass\r\na2 LIST \"\" \"*\"\r\na3 LOGOUT\r\n" | nc localhost 1143 |
|
107
|
``` |
|
108
|
|
|
109
|
### Check INBOX Status |
|
110
|
```bash |
|
111
|
printf "a1 LOGIN user pass\r\na2 STATUS INBOX (MESSAGES RECENT UNSEEN)\r\na3 LOGOUT\r\n" | nc localhost 1143 |
|
112
|
``` |
|
113
|
|
|
114
|
### Read Messages |
|
115
|
```bash |
|
116
|
printf "a1 LOGIN user pass\r\na2 SELECT INBOX\r\na3 FETCH 1:* (FLAGS BODY[])\r\na4 LOGOUT\r\n" | nc localhost 1143 |
|
117
|
``` |
|
118
|
|
|
119
|
## Testing |
|
120
|
|
|
121
|
### Run Unit Tests |
|
122
|
```bash |
|
123
|
cargo test |
|
124
|
``` |
|
125
|
|
|
126
|
### Run Example Client |
|
127
|
```bash |
|
128
|
cargo run --example imap_client |
|
129
|
``` |
|
130
|
|
|
131
|
### Manual Testing |
|
132
|
1. Start the server: `cargo run` |
|
133
|
2. Connect with netcat: `nc localhost 1143` |
|
134
|
3. Send IMAP commands interactively |
|
135
|
|
|
136
|
## Limitations and Future Enhancements |
|
137
|
|
|
138
|
### Current Limitations |
|
139
|
- No persistent storage (messages lost on restart) |
|
140
|
- Simplified authentication (accepts any credentials) |
|
141
|
- No SSL/TLS support for IMAP |
|
142
|
- Limited SEARCH criteria support |
|
143
|
- No support for mailbox hierarchy separators |
|
144
|
- No IDLE, APPEND, or COPY commands |
|
145
|
|
|
146
|
### Potential Enhancements |
|
147
|
- Persistent storage (database or file system) |
|
148
|
- Real authentication system |
|
149
|
- STARTTLS/SSL support for IMAP |
|
150
|
- Full SEARCH command support |
|
151
|
- IDLE command for push notifications |
|
152
|
- APPEND command for storing messages |
|
153
|
- COPY/MOVE commands for message management |
|
154
|
- Quota management |
|
155
|
- Access control lists (ACLs) |
|
156
|
|
|
157
|
## Security Considerations |
|
158
|
|
|
159
|
1. **Authentication**: Current implementation accepts any credentials - implement proper authentication for production |
|
160
|
2. **Encryption**: No TLS support yet - add STARTTLS for secure connections |
|
161
|
3. **Input Validation**: Basic validation implemented - add more robust checks |
|
162
|
4. **Resource Limits**: No limits on mailbox size or connection count - add limits for production |
|
163
|
|
|
164
|
## Performance Notes |
|
165
|
|
|
166
|
- Thread-safe using `Arc<Mutex<>>` for shared state |
|
167
|
- Async I/O with Tokio for efficient connection handling |
|
168
|
- Messages stored in memory for fast access |
|
169
|
- Supports concurrent SMTP and IMAP operations |
|
170
|
|
|
171
|
## Compliance |
|
172
|
|
|
173
|
The implementation follows RFC 3501 (IMAP4rev1) for core functionality: |
|
174
|
- Protocol state management ✓ |
|
175
|
- Command syntax and responses ✓ |
|
176
|
- Message flags ✓ |
|
177
|
- UID support ✓ |
|
178
|
- Mailbox operations ✓ |
|
179
|
|
|
180
|
Not yet implemented: |
|
181
|
- Full SEARCH criteria |
|
182
|
- All FETCH data items |
|
183
|
- Mailbox subscriptions |
|
184
|
- Message sequence number updates after expunge |
|
185
|
|
|
186
|
## Contributing |
|
187
|
|
|
188
|
When extending the IMAP implementation: |
|
189
|
1. Follow existing code patterns |
|
190
|
2. Add unit tests for new functionality |
|
191
|
3. Update this documentation |
|
192
|
4. Test with standard IMAP clients (Thunderbird, Mail.app, etc.) |
|
193
|
5. Ensure thread safety for concurrent access |