102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
# Technical Overview
|
|
|
|
## Mục đích
|
|
|
|
Tài liệu này là technical overview hiện hành của `Email-OpenClaw Bridge`. `README.md` chỉ giữ phần onboarding và vận hành cơ bản; phần này giữ các chi tiết kỹ thuật bền vững hơn về flow, package layout, state machine và công nghệ chính.
|
|
|
|
## Luồng xử lý
|
|
|
|
Bridge xử lý email theo pipeline sau:
|
|
|
|
```text
|
|
Ingress (IMAP) → Safety Checks → External Rules → Dispatch (OpenClaw) → Callback → Egress (SMTP reply)
|
|
```
|
|
|
|
Các giai đoạn runtime chính:
|
|
|
|
1. IMAP watcher theo dõi `INBOX` bằng IDLE và fetch email chưa đọc.
|
|
2. Safety checks loại bỏ mail từ chính hệ thống và chặn duplicate theo `message_id`.
|
|
3. External rules pipeline áp whitelist/blocklist và sinh `DispatchContext`.
|
|
4. Thread resolution gắn `thread_id` dựa trên quan hệ email đã biết.
|
|
5. Task được lưu vào SQLite với trạng thái pipeline hiện tại.
|
|
6. OpenClaw nhận request xử lý và callback về bridge.
|
|
7. Callback cập nhật `AIResponse`, sau đó bridge gửi phản hồi lại qua SMTP.
|
|
|
|
## Package layout
|
|
|
|
- `cmd/bridge`
|
|
- Entrypoint của process, wiring config, DB, IMAP watcher, HTTP router và SMTP egress.
|
|
- `internal/config`
|
|
- Đọc `.env`, chuẩn hóa default như `LISTEN_ADDR`, `CALLBACK_BASE_URL`, và validate biến bắt buộc.
|
|
- `internal/database`
|
|
- Khởi tạo SQLite qua GORM, định nghĩa `Task` model, repository helpers và health check DB.
|
|
- `internal/mail`
|
|
- Chứa IMAP ingress, thread resolution, proxy support cho IMAP, retry logic và SMTP egress.
|
|
- `internal/rules`
|
|
- External rules pipeline, whitelist/blocklist rules và rule metadata dùng cho dispatch.
|
|
- `internal/ai_client`
|
|
- HTTP client gọi OpenClaw và gửi metadata/callback information ra ngoài.
|
|
- `internal/api`
|
|
- HTTP router cho `healthz`, `readyz` và `POST /callback`.
|
|
- `internal/logging`
|
|
- Helper tạo structured logger theo `task_uuid`, `thread_id`, `message_id`.
|
|
|
|
## Task state machine
|
|
|
|
Task được lưu trong SQLite và đi qua các trạng thái sau:
|
|
|
|
```text
|
|
RECEIVED → AI_PROCESSING → CALLBACK_DONE → COMPLETED
|
|
↓ ↓ ↓
|
|
IGNORED FAILED SMTP_RETRYING → FAILED
|
|
```
|
|
|
|
- `IGNORED`
|
|
- Mail bị anti-loop, duplicate, hoặc bị external rules reject.
|
|
- `RECEIVED`
|
|
- Task đã được lưu và sẵn sàng dispatch.
|
|
- `AI_PROCESSING`
|
|
- Request đã được gửi sang OpenClaw.
|
|
- `CALLBACK_DONE`
|
|
- Callback hợp lệ đã cập nhật `AIResponse`.
|
|
- `SMTP_RETRYING`
|
|
- Đang retry gửi email phản hồi.
|
|
- `COMPLETED`
|
|
- Toàn bộ pipeline kết thúc thành công.
|
|
- `FAILED`
|
|
- Hết retry hoặc gặp lỗi không recoverable.
|
|
|
|
## HTTP và health behavior
|
|
|
|
- `GET /healthz`
|
|
- Trả `200 {"status":"ok"}` nếu process đang sống.
|
|
- `GET /readyz`
|
|
- Trả `200` khi DB writable và `BRIDGE_CALLBACK_TOKEN` có mặt.
|
|
- Trả `503` nếu DB không writable hoặc config bắt buộc cho callback chưa sẵn sàng.
|
|
- `POST /callback`
|
|
- Yêu cầu header `X-Bridge-Token`.
|
|
- Nhận payload callback từ OpenClaw, cập nhật task và kích hoạt SMTP egress bất đồng bộ.
|
|
|
|
## Công nghệ chính
|
|
|
|
- Go
|
|
- Runtime chính, phù hợp với service nhỏ gọn và dễ deploy.
|
|
- SQLite + GORM
|
|
- Giữ state cục bộ đơn giản, không cần service DB riêng cho v1.
|
|
- `github.com/emersion/go-imap/v2`
|
|
- Hỗ trợ IMAP IDLE và xử lý mailbox theo flow hiện tại.
|
|
- `gin-gonic/gin`
|
|
- Cung cấp HTTP router tối giản cho health endpoints và callback.
|
|
- `log/slog`
|
|
- Structured logging chuẩn thư viện chuẩn của Go.
|
|
|
|
## ADR liên quan
|
|
|
|
- [ADR 0001: IMAP thread resolution prefers In-Reply-To and falls back to References](../adr/0001-imap-thread-resolution.md)
|
|
- [ADR 0002: Ingress uses a configurable external rules pipeline before dispatch](../adr/0002-external-rules-pipeline.md)
|
|
- [ADR index](../adr/README.md)
|
|
|
|
## Tài liệu lịch sử
|
|
|
|
- Historical design input: [docs/specs/2026-04-24-email-openclaw-bridge-design.md](../specs/2026-04-24-email-openclaw-bridge-design.md)
|