Module filters 

Mail filters, on the server (docs/client.md, “Filters”; what they say and how a message is matched: sioul_core::rules).

After each fetch, on every device that fetches (the window’s watchers, a phone’s background step, sioul watch), the inbox’s arrivals still unread are judged as the Porch judges them, what it protects left out (mail set aside, hostile mail, the spam filter’s review queue, a code you asked for), and what the filters that match say is done on the server: flags and keywords first, then the move, one command per folder. Never on an account’s first fetch (its last two weeks), never on what was there before: running them on the whole inbox is yours to ask (run, unmarked).

No race between devices: before acting, a device marks the message $SioulFiltered (rules::FILTERED) and acts only on what it marked. With CONDSTORE (RFC 7162), the mark is set only if nothing changed the message since its flags were read (UNCHANGEDSINCE): of two devices fetching it in the same instant, one marks it, the other’s store fails and it leaves the message alone. Without CONDSTORE, the flags are read, then the mark set: two devices would have to read in the same round trip. A message read meanwhile, or gone from the inbox, is left alone. An act that fails takes the mark off again, and the message waits for the next fetch here (Waiting: three tries, two days) or another device’s. A server that keeps no keywords of its own (no \* in PERMANENTFLAGS: Exchange, Outlook.com) cannot carry the mark: each device acts on what it fetched; a move, a flag or a read mark done twice leaves the message as once.

What is told (Done::to_tell, for the new-mail notifications): a message a filter could not act on here is told as any new mail is, by the device that fetched it; one it acted on, read meanwhile or gone, is not. One another device marked is that device’s to do: not told here yet, it waits here too and is looked at again at the next fetch (the other device’s act wakes the inbox’s watcher). Unmarked and still there, unread, it is this device’s to do; still marked ten minutes on (STUCK: that device stopped half-way), this device takes it over: it takes the mark off, only if nothing changed the message meanwhile (CONDSTORE), marks it again as its own and acts, so that no message stays marked and unfiltered for good. An act that fails then is told and tried again, as any.

Structs

Done

What became of a run.

Job

One message of an inbox, and what the filters do to it.

Wait 🔒

Waiting 🔒

Messages whose filtering failed here, tried again at the next fetches (three tries in two days at most), and those another device marked, looked at again until it acts or STUCK ($XDG_STATE_HOME/sioul/filters/waiting.toml, by account and place on the server; never a word of the message).

Enums

Failure

Why a message could not be filtered.

Found 🔒

What a device may do with a message it is to filter, by its flags on the server now.

Constants

RETRY 🔒

A failure is tried again this long after the last try at least (counted from the first).

STUCK 🔒

Another device’s mark that stays this long, the message neither read nor gone: that device stopped half-way (closed, out of battery, out of reach).

TRIES 🔒

WAITS 🔒

Functions

after_fetch

After a fetch of account’s inbox (new: its arrivals, oldest first, none at all when only something waits): those still unread, and those an earlier look left waiting (a failure, another device’s mark), filtered on the server, each marked first. Nothing on its first fetch.

claimed 🔒

The jobs this device may do: those still unread (or tried before), not marked by another device, still in the inbox, and those another device marked and left (Found::Stuck), their mark taken off first; then marked, each only if nothing changed it since its flags were read (CONDSTORE), else all at once.

due

Whether messages of account are due for another look here (another device’s mark to see through; a failure to try again, ten minutes after the last try at least): its next fetch runs the filters for them, new mail or not.

folder_named

The folder of account a filter names: as you read it (“Banque”, “Factures/2026”), else as its server writes it (“INBOX.Banque”), case aside, and the levels’ separator, “/” or “.”, either way.

follow_here 🔒

The copy here, once the server took a job: gone when it left the inbox (the next fetch brings it into its folder), else its new flags.

found 🔒

What a device may do with job’s message, from its flags on the server (flags: read, marked; none: gone from the inbox), now in Unix seconds.

inbox_files

The messages of account’s inbox kept here, read or not.

jobs

What the filters do to these messages of account’s inbox, judged as the Porch judges them now: what it protects, and what no filter takes, left out.

run

The plans done on account’s inbox, in one session: with claim, each message marked first, and left alone when another device marked it, it was read meanwhile or it left the inbox (after a fetch); without, every job, as you asked (the whole inbox). The copies here follow.

run_in 🔒

stored 🔒

A STORE, and the messages the server says it changed, by UID, each with its new mod-sequence when the server counts changes (RFC 7162 §3.1.3).

target 🔒

The server’s name of the folder a plan sends a message to; none for the inbox itself.