Module labels 

The label log: what you said of messages, spam or not, for the spam filter to learn from. One JSON line per act, added at the end of a file and never rewritten: “Junk” and “Not junk” (the Mail page, sioul mail), “Spam” and “Not spam” (the Porch’s review queue, the Reader), a sender blocked from one of their messages.

Each device writes its own log, $XDG_STATE_HOME/sioul/spam/labels/<device>.jsonl (own_log: the device’s name in the sharing, a UUID made once), and reads every device’s: the logs travel sealed, with the part “Spam filter” (sioul-sync’s share), so that a message you said is not spam on one device is never flagged again on another, and the training, on your computer, learns from what you said on your phone. Before the logs were shared, each device kept one, labels.jsonl: still read, and moved into this device’s own the first time it writes.

A line names its message as its server does (the account, the folder, its UIDVALIDITY and UID) and by its Message-ID; never by its text: no subject, no address, no word of it.

{"at":1791360000,"account":"home","folder":"INBOX","uidvalidity":1700000000,"uid":4521,"message_id":"abc@example.org","label":"ham","source":"not-spam"}

The newest line about a message, every device’s together, wins, and the log wins over everything else: the folders and keywords the message is found in, and the filter’s own verdicts. Those are never written here but kept apart, in the same way, one file per device: what it moved into a Junk folder (the matrix’s “Move to spam”) under moved/ (Moved), what it flagged where it is (the matrix’s “Flag only”) under flagged/ (Flagged). The Porch lists them among the filter’s catches; the training learns from them as they are until you say otherwise: what was moved, as spam, as all mail in a Junk folder; what was flagged as probably spam, as spam; what was flagged as maybe spam, not at all, a doubt being no label, until you say.

Structs

Entry

One act, one line.

Moved

One message your own filter moved into its account’s Junk folder (the matrix’s “Move to spam”), from where it was; in the log of what it flagged (Flagged), one it flagged where it is. No word of yours: the Porch lists it among the filter’s catches while it is there, and the training learns from it as the module says, until you say otherwise.

Enums

Label

What you said a message is.

Source

What you did to say it.

Constants

FILE

The older single log’s file name, in the spam filter’s state folder.

FLAGGED

The folder of the logs of what your own filter flagged where it is, one file per device.

FOLDER

The folder of the label logs, one file per device.

LOOKED 🔒

How long the logs’ folder listing is trusted before it is looked at again: the Porch asks about each message it sorts.

MOVED

The folder of the logs of what your own filter moved, one file per device.

Functions

append_to

Adds line at the end of the log at path: one line written whole, under the file’s lock (filelock), so two writers never mix their lines. The file is made yours alone, in a folder of yours alone (Unix).

file_safe 🔒

A device’s name as a file name: letters, digits, - and _.

kept 🔒

f on every device’s label log, read again when one of the files changed (its size or its time) or came: the folder is looked at again after two seconds at most.

logs_in 🔒

The logs in a folder, every device’s (*.jsonl, by name), and older before them when it is there.

message_id_of 🔒

A stored message’s Message-ID, bare, read from its headers alone (the first 256 KB of the file at most), as its card reads it.

newest_by_message_id

The newest entry about each message, by its Message-ID: the copies of one message in several folders or accounts are one. entries oldest first.

newest_for

The newest entry about one message, as its server names it. entries oldest first.

own_flagged_log

This device’s own log of what your filter flagged where it is under root, flagged/<device>.jsonl.

own_log

This device’s own label log under root (the spam filter’s state folder), labels/<device>.jsonl; device is its name in the sharing (a UUID made once: sioul-sync’s share::Here). The older single log, this device’s own, becomes it the first time.

own_moved_log

This device’s own log of what your filter moved under root, moved/<device>.jsonl.

read_all

Every device’s label log, here: read_all_in of this device’s state folder.

read_all_in

Every entry of every device’s label log under root (the spam filter’s state folder), the older single log’s too, oldest first: by when you said it, then in the order written.

read_flagged_in

Every device’s log of what your filter flagged where it is, under root, oldest first.

read_from

Every line of the log at path, in the order they were written; a line that cannot be read, cut by a crash or written by a later Sioul, is left out.

read_judged 🔒

Every line of the logs of folder (moved/, flagged/), oldest first.

read_moved_in

Every device’s log of what your filter moved, under root, oldest first.

said_ham

Whether you said the message on card is not spam, here, on another device or in another mail client, so that the Porch keeps your filter’s word and your provider’s off it for good: the $NotJunk keyword without $Junk in its file name (kept by each sync: maildir::keywords_of); else every device’s label log, whose newest entry about this message says so.

said_ham_in

Whether the newest entry of entries (oldest first) about the message on card says it is not spam: an entry of its account with its Message-ID, wherever the message was then (the logs of other devices name it by the folder it was in there); for a message without one, an entry without one at its very place (its UIDVALIDITY and UID).

seal_of 🔒

state

The spam filter’s state folder on this device: $XDG_STATE_HOME/sioul/spam.

unreviewed

Whether a message your filter moved or flagged is still as it judged it: no entry of the label logs (entries, oldest first) about it since.

Type Aliases

Flagged

One message your own filter flagged where it is (the matrix’s “Flag only”) as it arrived: the same line as a move, in its own log (flagged/). The training learns a probable spam flagged so as spam, and leaves a maybe spam out, until you say.

Seal 🔒

What the logs’ files were when read: their names, sizes and times.