MessageWeave/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 instance and a JMAP session plus a Telegram bot token.

This is a local container smoke test. Production deployment can use any platform that can run the backend container, inject encrypted secrets, and connect to externally managed Redis. See docs/deployment.md §3 and the platform-specific reference in docs/reference.md.

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 and enter your CONFIG_ENCRYPTION_KEY value. The SPA exchanges it with POST /api/admin/session for a 900-second admin session, then writes the business secrets to Redis with PUT /api/business-config. 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, 1 optional.

Variable	Required	Default
REDIS_URL	yes	—
CONFIG_ENCRYPTION_KEY	yes	—
PORT	no	8080

There is no RUN_MODE: the legacy environment parser was removed, and webhook plus reconcile traffic share one router (POST /reconcile is a standalone endpoint). .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. The only rule for running it is to keep it off: leave --debug out of the start command and leave DEBUG_TOKEN unset. If you do turn it on for a one-off diagnosis, configure the chat allowlist first — with an empty allowlist the test send is not restricted to any chat. 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/opengaps.md	Gaps, blockers and the next phase
docs/retired.md	What was tried and dropped — abandoned routes, unreleased designs, and names that never existed
docs/charter.md	Project charter: goals, locked technology choices, security invariants, prohibitions, and the stable-ID registry
AGENTS.md	Language-agnostic engineering norms: code style, config and secrets, build environment, testing gates, document governance

Facts that matter are traceable. If two documents disagree, docs/reference.md wins.