Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-imap

Source of release 0.6.0

0.6.0 / src / imap / messages.lucb

#==============================================================================================
#
#   imap/messages - Selecting a mailbox and working on its messages
#
#   DESCRIPTION:
#       `select` opens a mailbox and records its state. The message commands then work
#       by UID: `fetch` returns one Fetched record a message (UID, flags, size, internal
#       date, mod-sequence, and the header or body sections asked for), `search` the UIDs
#       a criterion matches, `store` changes flags, `copy` and `move` file messages
#       elsewhere (MOVE when the server has it, COPY + \Deleted + expunge otherwise),
#       `expunge` removes what is marked deleted, `append` adds a message to a mailbox.
#
#==============================================================================================

## A message's system flags and common keywords, as bits.
pub enum Flags as u16:
    empty = 0
    seen = 1
    answered = 2
    flagged = 4
    deleted = 8
    draft = 16
    recent = 32
    forwarded = 64
    junk = 128
    not_junk = 256

## The flag names a server sends and a client sets, with their bits.
let flag_names: (str, u16)[9] = [
    ("\\Seen", 1), ("\\Answered", 2), ("\\Flagged", 4), ("\\Deleted", 8), ("\\Draft", 16),
    ("\\Recent", 32), ("$Forwarded", 64), ("$Junk", 128), ("$NotJunk", 256),
]

## One message a FETCH returned. Section bytes last until the next command.
pub struct Fetched:
    pub var sequence: u32
    pub var uid: u32
    pub var flags: Flags
    ## Whether the response named the flags at all.
    pub var has_flags: bool
    pub var size: u64
    ## INTERNALDATE in seconds since 1970 UTC; zero when not fetched.
    pub var internal_date: i64
    pub var modseq: u64
    ## The bytes of a header section (BODY[HEADER…], RFC822.HEADER), when fetched.
    pub var header: const u8[]
    ## The bytes of any other section (BODY[], BODY[TEXT], RFC822), when fetched.
    pub var body: const u8[]

    ## Whether the message has flag `flag`.
    pub func is(flag: Flags) -> bool:
        return (self.flags & flag) != Flags.empty

## Append `flags` as a parenthesised flag list: `(\Seen \Flagged)`.
pub func write_flags(flags: Flags, out: collections.Buffer*) -> !:
    try out.put_byte('(')
    var first = true
    for entry in flag_names:
        if entry.1 == 32:
            continue
        if ((u16)flags & entry.1) != 0:
            if not first:
                try out.put_byte(' ')
            first = false
            try out.put_text(entry.0)
    try out.put_byte(')')

let month_abbreviations: str[12] = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"]

## Days from 1970-01-01 to a civil date (proleptic Gregorian).
func days_from_civil(year: i64, month: i64, day: i64) -> i64:
    let y = year - 1 if month <= 2 else year
    let era = (y if y >= 0 else y - 399) // 400
    let year_of_era = y - era * 400
    let day_of_year = (153 * (month - 3 if month > 2 else month + 9) + 2) // 5 + day - 1
    let day_of_era = year_of_era * 365 + year_of_era // 4 - year_of_era // 100 + day_of_year
    return era * 146097 + day_of_era - 719468

## The two-or-more digit number at `data[start..<end]`, or none.
func digits_at(data: const u8[], start: usize, end: usize) -> i64?:
    if end > data.length or start >= end:
        return none
    var value: i64 = 0
    for byte in data[start..<end]:
        if byte == ' ':
            continue
        if byte < '0' or byte > '9':
            return none
        value = value * 10 + (i64)(byte - '0')
    return value

## An INTERNALDATE, `17-Jul-1996 02:44:25 -0700`, in seconds since 1970 UTC; zero when
## it cannot be read.
pub func read_internal_date(text: const u8[]) -> i64:
    if text.length < 26:
        return 0
    let day = digits_at(text, 0, 2) else return 0
    var month: i64 = 0
    for index: usize in 0..<12:
        if same(text[3..<6], month_abbreviations[index].bytes):
            month = (i64)index + 1
    let year = digits_at(text, 7, 11) else return 0
    let hour = digits_at(text, 12, 14) else return 0
    let minute = digits_at(text, 15, 17) else return 0
    let second = digits_at(text, 18, 20) else return 0
    let zone = digits_at(text, 22, 26) else return 0
    if month == 0:
        return 0
    var offset = (zone // 100) * 60 + zone % 100
    if text[21] == '-':
        offset = -offset
    return days_from_civil(year, month, day) * 86400 + hour * 3600 + minute * 60 + second - offset * 60

extend Session:
    # mark: selecting ============================================================================

    ## Select mailbox `name` (UTF-8) to work on its messages; read-only with `read_only`
    ## (EXAMINE). The state is in `selected`.
    pub func select(name: str, read_only: bool = false) -> Selected!:
        self.has_selected = false
        self.selected = Selected()
        self.take_events()
        self.command.clear()
        try self.command.raw("EXAMINE " if read_only else "SELECT ")
        try self.command.mailbox(name.bytes)
        if self.has("CONDSTORE"):
            try self.command.raw(" (CONDSTORE)")
        try self.run(Collect.nothing)
        if read_only:
            self.selected.read_only = true
        self.has_selected = true
        # The counts just read are the starting state, not news.
        self.take_events()
        return self.selected

    ## Leave the selected mailbox without expunging (UNSELECT, or CLOSE when the server
    ## lacks it, which does expunge).
    pub func unselect() -> !:
        if not self.has_selected:
            return
        try self.simple("UNSELECT" if self.has("UNSELECT") else "CLOSE")
        self.has_selected = false

    func require_selected() -> !:
        if not self.has_selected:
            error(not_selected, "no mailbox is selected")

    # mark: fetching =============================================================================

    ## Fetch `items` (`(UID FLAGS BODY.PEEK[])`) of the messages in UID set `set`
    ## (`1:*`, `5,7:9`); `changed_since` > 0 asks only for messages whose mod-sequence is
    ## newer (CONDSTORE). Records last until the next command.
    pub func fetch(set: str, items: str, changed_since: u64 = 0) -> const Fetched[]!:
        try self.require_selected()
        self.reset_results()
        self.command.clear()
        try self.command.raw("UID FETCH ")
        try self.command.raw(set)
        try self.command.raw(" ")
        try self.command.raw(items)
        if changed_since > 0 and self.has("CONDSTORE"):
            try self.command.raw(" (CHANGEDSINCE ")
            try self.command.number(changed_since)
            try self.command.raw(")")
        try self.run(Collect.messages)
        return self.message_list.view()

    ## The records the last `fetch` returned.
    pub func fetched() -> const Fetched[]:
        return self.message_list.view()

    ## Read the current FETCH response into a record.
    func read_fetch() -> Fetched!:
        let response = &self.response
        var fetched = Fetched(sequence = response.number else 0, flags = Flags.empty)
        let items = response.at(response.values, 0) else return fetched
        var current = response.first(items)
        while let item = current:
            let value = response.next(item) else break
            let name = response.bytes(item)
            if same(name, b"UID"):
                fetched.uid = u32(response.number_of(value) else 0)
            elif same(name, b"FLAGS"):
                fetched.has_flags = true
                var flag = response.first(value)
                while let node = flag:
                    for entry in flag_names:
                        if same(response.bytes(node), entry.0.bytes):
                            fetched.flags = fetched.flags | (Flags)entry.1
                    flag = response.next(node)
            elif same(name, b"RFC822.SIZE"):
                fetched.size = response.number_of(value) else 0
            elif same(name, b"INTERNALDATE"):
                var text: collections.Buffer
                defer text.destroy()
                try response.string(value, &text)
                fetched.internal_date = read_internal_date(text.view())
            elif same(name, b"MODSEQ"):
                if let number = response.first(value):
                    fetched.modseq = response.number_of(number) else 0
            elif starts(name, b"BODY[") or starts(name, b"RFC822") or starts(name, b"BINARY["):
                var data: collections.Buffer
                defer data.destroy()
                try response.string(value, &data)
                let kept = try self.pool.keep(data.view())
                if contains_word(name, b"HEADER") or same(name, b"RFC822.HEADER"):
                    fetched.header = kept
                else:
                    fetched.body = kept
            current = response.next(value)
        return fetched

    ## The headers named in `fields` (`DATE FROM SUBJECT`), plus UID, flags, size and
    ## internal date, of the messages in UID set `set`: what a message list needs.
    pub func fetch_headers(set: str, fields: str) -> const Fetched[]!:
        var items: collections.Buffer
        defer items.destroy()
        try items.put(b"(UID FLAGS RFC822.SIZE INTERNALDATE")
        if self.has("CONDSTORE"):
            try items.put(b" MODSEQ")
        try items.put(b" BODY.PEEK[HEADER.FIELDS (")
        try items.put_text(fields)
        try items.put(b")])")
        return try self.fetch(set, (str)items.view())

    ## The whole message with UID `uid`, without marking it seen; empty when it is gone.
    pub func fetch_message(uid: u32) -> const u8[]!:
        var set: collections.Buffer
        defer set.destroy()
        try put_decimal(&set, uid)
        let records = try self.fetch((str)set.view(), "(UID BODY.PEEK[])")
        for record in records:
            if record.uid == uid:
                return record.body
        var none_found: const u8[]
        return none_found

    # mark: searching ============================================================================

    ## The UIDs of the messages matching `criteria` (`ALL`, `UNSEEN`, `SINCE 1-Oct-2026`),
    ## in ascending order. They last until the next command.
    pub func search(criteria: str) -> const u32[]!:
        try self.require_selected()
        self.reset_results()
        self.command.clear()
        try self.command.raw("UID SEARCH ")
        if self.has("ESEARCH"):
            try self.command.raw("RETURN (ALL) ")
        try self.command.raw(criteria)
        try self.run(Collect.search)
        sort(self.found.items())
        return self.found.view()

    ## The UIDs of the messages whose header or body holds `text` (SEARCH TEXT), in
    ## ascending order. Text outside ASCII is sent as UTF-8 (CHARSET UTF-8, as a literal
    ## unless the server accepts UTF-8 in quoted strings).
    pub func search_text(text: str) -> const u32[]!:
        try self.require_selected()
        self.reset_results()
        self.command.clear()
        try self.command.raw("UID SEARCH ")
        if self.has("ESEARCH"):
            try self.command.raw("RETURN (ALL) ")
        var ascii = true
        for byte in text.bytes:
            if byte >= 0x80:
                ascii = false
        if not ascii and not self.command.utf8:
            try self.command.raw("CHARSET UTF-8 ")
        try self.command.raw("TEXT ")
        try self.command.string(text.bytes)
        try self.run(Collect.search)
        sort(self.found.items())
        return self.found.view()

    ## Take in an ESEARCH response: `* ESEARCH (TAG "a5") UID ALL 4:19,21`.
    func read_esearch() -> !:
        let response = &self.response
        var current = response.first(response.values)
        while let item = current:
            if response.is_atom(item, "ALL"):
                let value = response.next(item) else return
                try add_set(response.bytes(value), &self.found)
                return
            current = response.next(item)

    # mark: changing messages ====================================================================

    ## Add (`add`) or remove flags `flags` on the messages in UID set `set`, silently.
    pub func store(set: str, flags: Flags, add: bool) -> !:
        try self.require_selected()
        self.command.clear()
        try self.command.raw("UID STORE ")
        try self.command.raw(set)
        try self.command.raw(" +FLAGS.SILENT " if add else " -FLAGS.SILENT ")
        try write_flags(flags, &self.command.text)
        try self.run(Collect.nothing)

    ## Copy the messages in UID set `set` to mailbox `name` (UTF-8).
    pub func copy(set: str, name: str) -> !:
        try self.require_selected()
        self.command.clear()
        try self.command.raw("UID COPY ")
        try self.command.raw(set)
        try self.command.raw(" ")
        try self.command.mailbox(name.bytes)
        try self.run(Collect.nothing)

    ## Move the messages in UID set `set` to mailbox `name` (UTF-8).
    pub func move(set: str, name: str) -> !:
        try self.require_selected()
        if not self.has("MOVE"):
            try self.copy(set, name)
            try self.store(set, Flags.deleted, true)
            try self.expunge(set)
            return
        self.command.clear()
        try self.command.raw("UID MOVE ")
        try self.command.raw(set)
        try self.command.raw(" ")
        try self.command.mailbox(name.bytes)
        try self.run(Collect.nothing)

    ## Remove the messages marked \Deleted: only those in UID set `set` when the server
    ## has UIDPLUS, all of them otherwise (or when `set` is empty).
    pub func expunge(set: str = "") -> !:
        try self.require_selected()
        self.command.clear()
        if set.length > 0 and self.has("UIDPLUS"):
            try self.command.raw("UID EXPUNGE ")
            try self.command.raw(set)
        else:
            try self.command.raw("EXPUNGE")
        try self.run(Collect.nothing)

    ## Add message `data` to mailbox `name` (UTF-8) with `flags`; its UID when the server
    ## says (UIDPLUS), zero otherwise.
    pub func append(name: str, data: const u8[], flags: Flags = Flags.empty) -> u32!:
        self.reset_results()
        self.command.clear()
        try self.command.raw("APPEND ")
        try self.command.mailbox(name.bytes)
        try self.command.raw(" ")
        try write_flags(flags, &self.command.text)
        try self.command.raw(" ")
        try self.command.literal(data)
        try self.run(Collect.nothing)
        return self.appended

## Whether `name` holds `word` ignoring case: `BODY[HEADER.FIELDS (…)]` holds HEADER.
func contains_word(name: const u8[], word: const u8[]) -> bool:
    var index: usize = 0
    while index + word.length <= name.length:
        if same(name[index..<index + word.length], word):
            return true
        index += 1
    return false

## Append the numbers of sequence set `text` (`4:7,9`) to `out`.
func add_set(text: const u8[], out: collections.List[u32]*) -> !:
    var index: usize = 0
    while index < text.length:
        var first: u32 = 0
        while index < text.length and text[index] >= '0' and text[index] <= '9':
            first = first * 10 + (u32)(text[index] - '0')
            index += 1
        var last = first
        if index < text.length and text[index] == ':':
            index += 1
            last = 0
            while index < text.length and text[index] >= '0' and text[index] <= '9':
                last = last * 10 + (u32)(text[index] - '0')
                index += 1
        let low = first if first < last else last
        let high = last if first < last else first
        if high - low > 10000000:
            error(limit_exceeded, "a search result range is too large")
        var value = low
        while value <= high:
            try out.append(value)
            value += 1
        index += 1

## Sort `values` ascending: a shell sort, as results are mostly in order already.
func sort(values: u32[]):
    var gap = values.length // 2
    while gap > 0:
        for index in gap..<values.length:
            let value = values[index]
            var at = index
            while at >= gap and values[at - gap] > value:
                values[at] = values[at - gap]
                at -= gap
            values[at] = value
        gap = gap // 2