anonsaber
399b26918e
## 锚点重锚（afa6cec 之后）
④ 对 notify.rs 的编辑使一批 `notify.rs:N` 引用整体失效。全量重扫 8 个 md、
165 个 src 锚点，0 硬错误（越界 / 区间全空 / 单行指空行三类全查）。修正要点：
- reference.md（30+ 处）：dedup/committed/inflight/ratelimit 键调用点、
error_response 320-328、error_response_with_id 1087-1093、readiness 161、
router 1275 + routes 1304-1318、worker 330、main.rs 40/50/34/78-81、
NoopWorker 由 notify.rs 更正为 worker.rs:142-144、
PROBE_TIMEOUT 73 与 tokio::join! 147、state.rs 639。
- deployment.md：149-152→227-230、159/172→239/252、index.js 40-55→45-60。
- retired.md：704→717、887-890→897-900、326→330、873→884。
- roadmap.md：95→175；design.md：main.rs 109→128。
- cloudflare-worker 侧 4 处 stale：ROUTE_METHODS 45-60、404 77-78、
405 80-83、503 85-93。
## /debug/* 文档
- deployment.md 新增 §2.1：双因子门禁、7 条路由状态码表、/debug/config 字段清单、
三条部署约束、生产建议；§5 env 表补 --debug / DEBUG_TOKEN。
- README.md / README.zh-CN.md 各加一段「远程联调面（可选，默认关闭）」，指向 §2.1。
- design.md 新增 §7.6「为何默认绝对关闭」：双因子挂载、404 而非 401
（401 会泄漏路由存在性）、无默认开启回退、不在网关白名单内 fail-closed。
## 文档纠错（与任务书相反，已按源码核实）
- /debug/worker 是 GET 不是 POST（debug.rs:79）。
- /debug/config 不是「只出布尔」：明文回 jmap.{session_url,username}、
telegram.chat_id、llm.{base_url,model} 与全部 timeout/retry，
仅 5 个凭据字段出 *_configured。文档措辞改为「不含凭据，不是全脱敏」。
- 门禁位置更正：--debug 读 main.rs:99、DEBUG_TOKEN 读 main.rs:100-103、
merge 在 notify.rs:1320-1321（无 DEBUG_BASE 常量，路径为字面量）。
## AGENTS.md
- 版本基线 v3（代码
|
||
|---|---|---|
| .github/workflows | ||
| cloudflare-worker | ||
| docs | ||
| src | ||
| web | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| AGENTS.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| Dockerfile | ||
| README.md | ||
| README.zh-CN.md | ||
| hoststack.yaml | ||
README.md
MessageWeave
中文文档 / Chinese documentation → README.zh-CN.md
One Telegram bot per mailbox. New mail arrives as metadata; the original is always fetched read-only from your own JMAP server.
1. What it is
MessageWeave sits between a JMAP mail server (for example Stalwart) and a Telegram bot.
- Inbound. A JMAP push subscription tells the service that a message changed. Nothing is polled at rest.
- Outbound. Each event becomes a short, metadata-only Telegram notification: sender, subject, timestamp. Mail bodies are never sent to Telegram.
- On demand. When you ask, the service reads the original through a fresh JMAP read call. Nothing is cached in between.
- Optionally summarised. If you explicitly opt in, an OpenAI-compatible LLM returns a short summary. Requests, responses and attachment bytes are never persisted.
State is an architectural boundary here, not a preference.
- Redis is the only state store. No database, no embedded store, no second store.
- The process writes nothing to disk. No log files, no data files, no local volume.
- No long-lived connections. No SSE, no WebSocket, no long polling.
- Logs go to stdout only. The platform's collector owns log storage and retention.
- What it is not. It is not a mail client, not a proxy, and not a relay. It forwards metadata to one bot; it does not read arbitrary URLs, open tunnels, or broker traffic.
2. 5-minute setup
Requires a reachable Redis 7 instance and a JMAP session plus a Telegram bot token.
cp .env.example .env # fill REDIS_URL and CONFIG_ENCRYPTION_KEY
docker build -t messageweave:latest .
docker run --env-file .env -p 8080:8080 messageweave:latest
Then open http://localhost:8080 in a browser. The first-boot SPA calls
POST /api/bootstrap, stores the business secrets in Redis, and creates the admin session.
From that point the browser configures the service through Redis — no environment variable
is read or written again for business configuration.
For local builds without Docker: cargo build --locked produces the message-weave binary.
If the service answers requests but does nothing useful, check the logs for a startup warning: a missing required variable does not crash the process. It serves a read-only setup router over in-memory state instead. See §3.
3. Configuration entry points
Three layers. They are not interchangeable.
Boot-time environment — 2 required, 2 optional.
| Variable | Required | Default |
|---|---|---|
REDIS_URL |
yes | — |
CONFIG_ENCRYPTION_KEY |
yes | — |
PORT |
no | 8080 |
RUN_MODE |
no | webhook |
RUN_MODE accepts webhook or reconcile. .env.example ships only the two required
variables; the rest are documented defaults.
Business configuration — Redis, written by the browser.
POST /api/bootstrap is the one-shot trust bootstrap; PUT /api/business-config hot-
reloads individual settings within about one second. The process never reads business
secrets from the environment in normal operation.
Health.
GET /healthz returns 200 unconditionally — it is liveness, not readiness. GET /ready
returns 503 until configuration, Redis, and both upstreams (a JMAP session GET and
Telegram getMe, 3s each) are reachable. Probe /ready, not /healthz, when deciding
whether to route traffic — but /ready is the heavier probe (~3s worst case), so a monitor
that must stay cheap should watch the gateway's aggregated /healthz.
Remote debug (opt-in, off by default).
/debug/* is an optional remote-debug surface: live JMAP and Telegram probes, the current
business config, and a single Telegram send. It sits behind a two-factor gate — the process
must be started with --debug and DEBUG_TOKEN must be set; miss either and the routes
do not exist at all (requests fall through to a generic 404). Nothing under /debug/* is on
the gateway allowlist, so it is reachable only on the backend origin itself. See
docs/deployment.md §2.1.
4. Security boundary, in one sentence
All state lives in Redis; the process reads only two environment variables and writes nothing to disk.
One corollary matters for setup: the SPA admin credential — and therefore the bootstrap
trust root — is CONFIG_ENCRYPTION_KEY itself, the single 32-byte hex value you supply at
startup. It is only compared in constant time, and is never echoed, logged, or stored. The
Redis ACL password, if you have one, authenticates the Redis connection alone and is not
the credential for any HTTP endpoint.
5. Where to read more
| Document | What it answers |
|---|---|
docs/design.md |
Why the system is shaped this way: data flow, JMAP semantics, Redis streams, AI consent rules |
docs/deployment.md |
How to deploy: Dockerfile, secrets, Redis hosting, webhook/push/reconcile routing, multi-instance load balancing |
docs/reference.md |
Single source of truth for verifiable facts — Redis keys and TTLs, error codes, routes, environment layers, budgets |
docs/roadmap.md |
Gaps, blockers and the next phase |
docs/retired.md |
What was tried and dropped — abandoned routes, unreleased designs, and names that never existed |
AGENTS.md |
Contribution rules, hard boundaries, the stable-ID index for cross-document references |
Facts that matter are traceable. If two documents disagree, docs/reference.md wins.