update readme.md

Author: J0nasMayr

readme.md

@@ -74,11 +74,40 @@ public class App {
 
 The following configuration options are available:
 
-| Name                                   | Default     | Description                                                           |
-|----------------------------------------|-------------|-----------------------------------------------------------------------|
-| `lib.emailservice.migrations.enabled`  | true        | Enables database migrations.                                          |
-| `lib.emailservice.scheduling.enabled`  | true        | Enables the scheduler sending the emails.                             |
-| `lib.emailservice.scheduling.interval` | 30000       | Specifies the milliseconds delay between runs of the scheduler.       |
+| Name                                                                    | Default | Description                                                                                                            |
+|-------------------------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------------------------|
+| `aboutbits.emailservice.migrations.enabled`                             | true    | Enables database migrations.                                                                                           |
+| `aboutbits.emailservice.scheduling.enabled`                             | true    | Enables the scheduler sending the emails.                                                                              |
+| `aboutbits.emailservice.scheduling.cleanup.enabled`                     | true    | Enables cleanup of attachment files after sending.                                                                     |
+| `aboutbits.emailservice.scheduling.interval`                            | 30000   | Milliseconds delay between runs of the scheduler.                                                                      |
+| `aboutbits.emailservice.scheduling.stuck-sending-recovery-threshold`    | PT5M    | How long an email may stay in `SENDING` before being considered abandoned (crashed pod) and eligible to be re-claimed. |
+| `aboutbits.emailservice.scheduling.max-attempts`                        | 3       | Maximum number of send attempts before an email is marked as `ERROR`. Applies only to the scheduled retry loop.        |
+
+## Multi-pod deployments
+
+The scheduler is safe to run on every pod concurrently. Each pass performs
+three independent steps:
+
+1. **Candidate scan** — a plain `SELECT` returns up to `batch-size` ids of
+   emails whose `scheduled_at` has passed and whose state is `PENDING` or `SENDING`
+   older than `stuck-sending-recovery-threshold` (crashed-pod recovery). `ERROR`
+   is terminal: rows that exhausted `max-attempts` are never re-picked
+   automatically — an operator can reset them to `PENDING` if a retry is desired.
+   Two pods may see overlapping ids at this step, and that's fine — the atomic
+   claim below arbitrates.
+2. **Atomic claim** — for each candidate id, a single compare-and-set
+   `UPDATE … SET state = SENDING … WHERE id = ? AND state IN (PENDING, ERROR, staleSENDING)`
+   is issued. The database serializes concurrent updates against the same row so
+   exactly one pod sees `rowsAffected = 1` and owns that email; the other pods
+   see `0` and move on.
+3. **Send and persist** — the winning pod calls SMTP outside any database
+   transaction and then writes the final `SENT` / `ERROR` / `PENDING` state through a small `save()`.
+
+Crash recovery: if a pod dies between "claim" and "persist result", the row
+stays in `SENDING` with its `execution_start_time` frozen. After
+`stuck-sending-recovery-threshold` any pod's next pass picks it up as a
+candidate again and retries. Repeated crashes therefore count against
+`max-attempts` and eventually escalate the row to `ERROR` rather than looping forever.
 
 ## Local development: