@smbcloud / smbcloud-mail-imap
Code Commits Issues Pulls Cloud Agent CI/CD
copilot/add-pop3-protocol-examples
copilot/add-pop3-protocol-examples copilot/add-pop3-protocol-implementation copilot/implement-mail-handling-separation development main
md 379 lines 8.51 KB
Rendered Raw
1 # POP3 Examples and Documentation - Quick Reference
2
3 This document provides a quick reference to all POP3 examples and documentation in this repository.
4
5 ## 📚 Documentation Files
6
7 ### Main Documentation
8 - **[POP3.md](POP3.md)** - Comprehensive POP3 protocol documentation
9 - Protocol basics and command reference
10 - Setup and configuration guide
11 - Integration with SMTP and IMAP
12 - Troubleshooting guide
13 - Best practices
14
15 ### Configuration
16 - **[config-examples.md](config-examples.md)** - Configuration examples
17 - Basic configurations for development
18 - Production configurations with TLS
19 - Database and LDAP authentication
20 - Docker and cluster configurations
21 - Environment-specific settings
22
23 ### Testing
24 - **[TESTING.md](TESTING.md)** - Comprehensive testing guide
25 - Unit testing examples
26 - Integration testing patterns
27 - Mock testing strategies
28 - Load testing examples
29 - Security testing
30 - CI/CD setup
31
32 ### Scenarios
33 - **[SCENARIOS.md](SCENARIOS.md)** - Real-world usage scenarios
34 - Basic email retrieval
35 - Download and delete workflows
36 - Selective message management
37 - Mobile client scenarios
38 - Email backup solutions
39 - Multi-device synchronization
40 - Email migration
41 - Automated processing
42 - Error recovery
43
44 ## 💻 Code Examples
45
46 ### Rust Examples
47
48 #### 1. POP3 Client (`examples/pop3_client.rs`)
49 Complete POP3 client implementation demonstrating:
50 - Connection to POP3 server
51 - USER/PASS authentication
52 - STAT command (mailbox statistics)
53 - LIST command (message listing)
54 - RETR command (message retrieval)
55 - DELE command (message deletion)
56 - RSET command (reset deletions)
57 - NOOP command (keepalive)
58 - QUIT command (close connection)
59 - Error handling for all operations
60
61 **Run it:**
62 ```bash
63 cargo run --example pop3_client
64 ```
65
66 **Example output:**
67 ```
68 ===========================================
69 POP3 Client Examples
70 ===========================================
71
72 This example demonstrates various POP3 operations.
73 Note: These examples assume a POP3 server is running on localhost:110
74
75 EXAMPLE 1: Complete Email Retrieval Session
76 ========================================
77 Connecting to localhost:110...
78 ```
79
80 #### 2. POP3 Server (`examples/pop3_server.rs`)
81 Mock POP3 server implementation for testing:
82 - Multi-threaded connection handling
83 - User authentication
84 - Mailbox management
85 - All standard POP3 commands
86 - Sample test data
87
88 **Run it:**
89 ```bash
90 cargo run --example pop3_server
91 ```
92
93 **Features:**
94 - Pre-configured test users (testuser/testpass, alice/password123, bob/secret)
95 - Sample messages for testing
96 - Proper POP3 protocol responses
97 - Transaction state management
98
99 #### 3. Integration Tests (`examples/pop3_integration_test.rs`)
100 Comprehensive integration test suite with:
101 - Basic authentication tests
102 - Message operation tests
103 - Deletion workflow tests
104 - Error handling tests
105 - Complete session tests
106 - Concurrent connection tests
107 - Command sequencing tests
108
109 **Run it:**
110 ```bash
111 cargo run --example pop3_integration_test
112 ```
113
114 **Test Coverage:**
115 - ✅ 7 integration test scenarios
116 - ✅ Mock server implementation
117 - ✅ Concurrent client testing
118 - ✅ Error condition testing
119
120 ### Python Examples
121
122 #### POP3 Client (`docs/scripts/pop3-client.py`)
123 Python implementation using `poplib` library:
124 - 9 complete example scenarios
125 - All major POP3 operations
126 - Email parsing with `email` library
127 - Secure POP3S support
128 - Comprehensive error handling
129
130 **Run it:**
131 ```bash
132 python3 docs/scripts/pop3-client.py
133 ```
134
135 **Examples included:**
136 1. Basic connection and authentication
137 2. List all messages
138 3. Retrieve and parse message
139 4. Retrieve all messages
140 5. Delete messages
141 6. TOP command (headers only)
142 7. UIDL command (unique IDs)
143 8. Error handling scenarios
144 9. Secure POP3S connection
145
146 ## 🚀 Quick Start
147
148 ### 1. Basic POP3 Client Usage
149
150 ```rust
151 use std::io::{BufRead, BufReader, Write};
152 use std::net::TcpStream;
153
154 fn main() -> Result<(), Box<dyn std::error::Error>> {
155 // Connect
156 let mut stream = TcpStream::connect("localhost:110")?;
157 let mut reader = BufReader::new(stream.try_clone()?);
158
159 // Read greeting
160 let mut line = String::new();
161 reader.read_line(&mut line)?;
162 println!("{}", line);
163
164 // Authenticate
165 writeln!(stream, "USER testuser")?;
166 reader.read_line(&mut line)?;
167
168 writeln!(stream, "PASS testpass")?;
169 line.clear();
170 reader.read_line(&mut line)?;
171
172 // Get statistics
173 writeln!(stream, "STAT")?;
174 line.clear();
175 reader.read_line(&mut line)?;
176 println!("Mailbox: {}", line);
177
178 // Close
179 writeln!(stream, "QUIT")?;
180
181 Ok(())
182 }
183 ```
184
185 ### 2. Using netcat for Manual Testing
186
187 ```bash
188 # Connect to POP3 server
189 nc localhost 110
190
191 # Then type these commands:
192 USER testuser
193 PASS testpass
194 STAT
195 LIST
196 RETR 1
197 DELE 1
198 QUIT
199 ```
200
201 ### 3. Python Quick Start
202
203 ```python
204 import poplib
205
206 # Connect and authenticate
207 pop3 = poplib.POP3("localhost", 110)
208 pop3.user("testuser")
209 pop3.pass_("testpass")
210
211 # Get statistics
212 message_count, mailbox_size = pop3.stat()
213 print(f"{message_count} messages, {mailbox_size} bytes")
214
215 # List messages
216 response, message_list, octets = pop3.list()
217 for msg in message_list:
218 print(msg.decode())
219
220 # Retrieve message
221 response, lines, octets = pop3.retr(1)
222 message = b'\n'.join(lines)
223 print(message.decode())
224
225 # Close
226 pop3.quit()
227 ```
228
229 ## 📋 Command Reference
230
231 ### Authorization State
232 | Command | Description | Example |
233 |---------|-------------|---------|
234 | `USER` | Username | `USER john@example.com` |
235 | `PASS` | Password | `PASS secretpassword` |
236
237 ### Transaction State
238 | Command | Description | Example |
239 |---------|-------------|---------|
240 | `STAT` | Get statistics | `STAT` → `+OK 5 3200` |
241 | `LIST` | List messages | `LIST` or `LIST 1` |
242 | `RETR` | Retrieve message | `RETR 1` |
243 | `DELE` | Mark for deletion | `DELE 1` |
244 | `NOOP` | No operation | `NOOP` |
245 | `RSET` | Reset deletions | `RSET` |
246 | `QUIT` | Close connection | `QUIT` |
247
248 ## 🔧 Configuration Examples
249
250 ### Basic Development Setup
251
252 ```toml
253 [server]
254 host = "127.0.0.1"
255 port = 110
256
257 [authentication]
258 backend = "file"
259 users_file = "users.txt"
260
261 [storage]
262 backend = "maildir"
263 maildir_path = "./mailboxes"
264 ```
265
266 ### Production Setup with TLS
267
268 ```toml
269 [server]
270 host = "0.0.0.0"
271 port = 995 # POP3S
272
273 [tls]
274 enabled = true
275 cert_path = "/etc/ssl/certs/mail.crt"
276 key_path = "/etc/ssl/private/mail.key"
277
278 [authentication]
279 backend = "database"
280 db_url = "postgresql://user:pass@localhost/maildb"
281
282 [storage]
283 backend = "maildir"
284 maildir_path = "/var/mail"
285 ```
286
287 ## 🧪 Testing
288
289 ### Run All Tests
290 ```bash
291 # Compile examples
292 cargo build --examples
293
294 # Run integration tests
295 cargo run --example pop3_integration_test
296
297 # Run Python examples
298 python3 docs/scripts/pop3-client.py
299 ```
300
301 ### Manual Testing with Server
302 ```bash
303 # Terminal 1: Start server
304 cargo run --example pop3_server
305
306 # Terminal 2: Connect with client
307 cargo run --example pop3_client
308 ```
309
310 ## 📊 Test Coverage
311
312 - **Unit Tests**: Command parsing, authentication, mailbox operations
313 - **Integration Tests**: Complete sessions, concurrent connections, error handling
314 - **Security Tests**: Rate limiting, injection protection, authentication
315 - **Load Tests**: Concurrent connections, message retrieval performance
316
317 ## 🔐 Security Best Practices
318
319 1. **Always use TLS/SSL in production** (POP3S on port 995)
320 2. **Use strong password hashing** (argon2, bcrypt)
321 3. **Implement rate limiting** for authentication attempts
322 4. **Validate all inputs** to prevent injection attacks
323 5. **Set appropriate timeouts** to prevent resource exhaustion
324 6. **Monitor and log** all authentication attempts
325 7. **Keep certificates up to date**
326
327 ## 🐛 Troubleshooting
328
329 ### Connection Refused
330 ```bash
331 # Check if server is running
332 netstat -an | grep :110
333
334 # Test connection
335 telnet localhost 110
336 ```
337
338 ### Authentication Fails
339 ```bash
340 # Check server logs
341 tail -f /var/log/pop3/server.log
342
343 # Test with known-good credentials
344 echo -e "USER testuser\r\nPASS testpass\r\nQUIT\r\n" | nc localhost 110
345 ```
346
347 ### Messages Not Found
348 ```bash
349 # List messages first
350 echo -e "USER testuser\r\nPASS testpass\r\nLIST\r\nQUIT\r\n" | nc localhost 110
351
352 # Check mailbox directory
353 ls -la /var/mail/testuser/new/
354 ```
355
356 ## 📖 Additional Resources
357
358 - **RFC 1939** - POP3 Protocol Specification
359 - **RFC 2595** - Using TLS with POP3
360 - **RFC 2449** - POP3 Extension Mechanism
361
362 ## 🤝 Contributing
363
364 When adding new examples or documentation:
365
366 1. Follow existing code style and structure
367 2. Add comprehensive comments
368 3. Include error handling
369 4. Provide working examples
370 5. Update this README
371 6. Add tests for new functionality
372
373 ## 📝 License
374
375 See the main repository LICENSE file for license information.
376
377 ---
378
379 **Need help?** Check the detailed documentation files or open an issue on GitHub.