first commit

docs/DEVELOPMENT.md

@@ -0,0 +1,78 @@
+# Development
+
+## Architecture
+
+```
+src/
+  main.rs            CLI (serve, admin, config, device, probe)
+  lib.rs             public router (ActiveSync, Autodiscover, /, /healthz)
+  app.rs             application state: settings (ArcSwap), IMAP pool, metrics, lockouts
+  config.rs          settings model (serde, validation, merging, secrets)
+  db.rs              SQLite (sqlx, WAL), migrations in migrations/, housekeeping
+  server.rs          HTTP/1.1 + HTTP/2 listener, optional TLS, graceful shutdown
+  wbxml/             WBXML encoder/decoder + MS-ASWBXML code pages
+  eas/               ActiveSync protocol
+    mod.rs           request parsing (plain/base64 query), auth, provisioning, dispatcher
+    state.rs         SyncKey {uuid}N and states (item fingerprints)
+    folders.rs       FolderSync / Create / Update / Delete
+    sync.rs          Sync, GetItemEstimate, MoveItems
+    ping.rs          Ping and the shared wait-for-changes loop (hanging Sync)
+    provision.rs     policies, remote wipe
+    mailcmd.rs       SendMail / SmartReply / SmartForward / MeetingResponse
+    itemops.rs       ItemOperations, GetAttachment
+    misc.rs          Settings, Search, ResolveRecipients
+    convert/         RFC 5322 / iCalendar / vCard <-> ApplicationData
+  backend/
+    imap.rs          own async IMAP client (literals, UIDPLUS, MOVE, SPECIAL-USE)
+    dav.rs           CalDAV/CardDAV client
+    smtp.rs          SMTP (lettre) / sendmail
+    ical.rs          iCalendar/vCard parser and serializer
+    tz.rs            EAS <-> IANA time zones, dates
+    mime.rs          MIME building (SmartReply/Forward)
+    mod.rs           session: folder hierarchy, fingerprint listings, operations
+  autodiscover.rs
+  admin.rs           panel API, sessions, CSRF, SSE, Prometheus
+web/                 panel (dependency-free HTML/CSS/JS, embedded in the binary)
+```
+
+### Synchronisation
+
+The device state of a folder is a map `item id -> fingerprint` (IMAP: flags; DAV: ETag) stored under the key
+`{uuid}N`. Sync compares the backend listing with the state and sends the differences (deletes -> changes ->
+adds, newest mail first) within `WindowSize`. The new state is stored as `N+1`; the previous one is kept to
+handle lost responses (the device replays the old key). Client adds are idempotent thanks to the `ClientId` map.
+
+Ping keeps a folder signature (IMAP `STATUS UIDNEXT/MESSAGES/UNSEEN/HIGHESTMODSEQ`, DAV CTag); a full listing
+comparison only happens when the signature changes.
+
+Collection ids that a device uses but that do not exist (Z-Push leftovers) are remembered per device and sent
+as FolderHierarchy Delete on the next FolderSync.
+
+## Development environment
+
+```bash
+sudo apt install dovecot-imapd           # any dovecot >= 2.3
+pip install radicale aiosmtpd
+./dev.sh backends                        # Dovecot :11143, Radicale :15232, SMTP sink :12525
+./dev.sh seed && ./dev.sh                # ActivePush :8081 / panel :9091
+./dev.sh e2e                             # test of every command against live backends
+```
+
+Test accounts: `jan`, `anna`, `biuro`, `kasia` `@test.local`, password `Test-Password-123`.
+
+`./dev.sh lint` - rustfmt, clippy `-D warnings`, JS syntax check and WBXML tag name check
+(`scripts/check-wbxml-names.py`). `./dev.sh test` - unit tests (WBXML, IMAP tokenizer, UTF-7, calendar/contact/
+task conversions, time zones, query parser, CIDR, MIME).
+
+Protocol debugging: add the login to **ActiveSync -> Logging -> Debug users**; decoded WBXML of requests and
+responses goes to the log.
+
+Simulating devices: `active-push probe --device-id F2LX8KQ1N72J --device-type iPhone --model "iPhone 15 Pro" ...`.
+
+## Documentation screenshots
+
+`tools/dev/screenshots.js` (Playwright) regenerates `docs/images/` from a running dev instance:
+
+```bash
+node tools/dev/screenshots.js http://127.0.0.1:9091 admin 'password'
+```