f9554e8 · smbcloud/smbcloud-mail-imap

@@ -0,0 +1,379 @@

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)** (21KB) - 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)** (12KB) - 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)** (20KB) - 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)** (24KB) - 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.

Add POP3 examples quick reference guide