Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-imap

Source of release 0.6.0

0.6.0 / src / imap / session.lucb

#==============================================================================================
#
#   imap/session - Commands run, responses dispatched, state kept
#
#   DESCRIPTION:
#       `Session.open` connects, reads the greeting, upgrades with STARTTLS when asked
#       and learns the capabilities. Every command goes through `run`: the session tags
#       it, sends it (pausing at synchronizing literals for the server's `+`), and reads
#       responses until its tagged completion. Untagged responses on the way are absorbed
#       (`absorb`): state (EXISTS, capabilities, response codes) is updated at once, and
#       data the command asked for (LIST, FETCH, SEARCH, STATUS) goes into the result
#       lists; other FETCH and EXPUNGE responses become events. NO, BAD and BYE fail the
#       command with the server's text.
#
#==============================================================================================

## What the running command collects from untagged responses.
enum Collect as u8:
    nothing = 0
    mailboxes = 1
    messages = 2
    search = 3
    status = 4

## The state of the selected mailbox.
pub struct Selected:
    pub var exists: u32
    pub var recent: u32
    pub var uid_validity: u32
    pub var uid_next: u32
    ## Zero when the server has no CONDSTORE.
    pub var highest_modseq: u64
    ## The sequence number of the first unseen message, zero when not given.
    pub var first_unseen: u32
    pub var read_only: bool

## A connection to one IMAP server.
pub struct Session:
    var link: Link
    var reader: Reader
    var response: Response
    var command: Command
    var tag_number: u32
    ## Capability names upper-cased, each between spaces: ` IMAP4REV1 IDLE `.
    var capabilities: collections.Buffer
    var authenticated: bool
    var has_selected: bool
    pub var selected: Selected
    ## The server's text from the last NO, BAD, BYE or ALERT, printable ASCII only.
    var last_text: collections.Buffer
    var collect: Collect
    ## A SASL answer to send at the next continuation request, then empty lines.
    var sasl: collections.Buffer
    var sasl_sent: bool
    # The results of the last command.
    var pool: collections.TextPool
    var mailbox_list: collections.List[Mailbox]
    var message_list: collections.List[Fetched]
    var found: collections.List[u32]
    var status_result: MailboxStatus
    var appended: u32
    # Events since the last `take_events`.
    var expunged: collections.List[u32]
    var changes: collections.List[Fetched]
    var exists_changed: bool
    # IDLE in progress: its tag.
    var idling: bool
    var idle_tag: collections.Buffer

    ## Connect to `host`, read the greeting, upgrade with STARTTLS when `security` asks
    ## for it, and learn the capabilities.
    pub static func open(host: str, port: u16, security: Security, timeout: u64 = default_timeout, cancellation: sync.Cancellation*? = none, trust: tls_stream.Trust = tls_stream.Trust()) -> Session!:
        let link = try Link.connect(host, port, security == Security.tls, timeout, cancellation, trust)
        var session = Session(link = link, selected = Selected(), collect = Collect.nothing)
        errdefer session.close()
        try session.greet()
        if security == Security.starttls:
            if not session.has("STARTTLS"):
                error(unsupported, "the server does not offer STARTTLS")
            try session.simple("STARTTLS")
            if session.reader.pending():
                error(protocol, "the server sent data after its STARTTLS answer")
            try session.link.start_tls(host, trust)
            session.capabilities.clear()
            try session.simple("CAPABILITY")
        return session

    ## A session over an already connected, plain `link` (tests, proxies).
    pub static func over(link: Link) -> Session!:
        var session = Session(link = link, selected = Selected(), collect = Collect.nothing)
        errdefer session.close()
        try session.greet()
        return session

    ## Read the greeting; learn the capabilities if it did not name them.
    func greet() -> !:
        let raw = try self.reader.read(&self.link)
        try self.response.parse(raw)
        if not self.response.is_untagged():
            error(protocol, "the server did not greet")
        try self.absorb()
        match self.response.status:
            .ok: self.authenticated = false
            .preauth: self.authenticated = true
            .bye: error(disconnected, self.text())
            _: error(protocol, "the server's greeting is not OK")
        if self.capabilities.length() == 0:
            try self.simple("CAPABILITY")

    ## Whether the server offers capability `name` (`IDLE`, `AUTH=PLAIN`), ignoring case.
    pub func has(name: str) -> bool:
        let data = self.capabilities.view()
        var index: usize = 0
        while index + name.length + 2 <= data.length:
            if data[index] == ' ' and data[index + name.length + 1] == ' ' and same(data[index + 1..<index + 1 + name.length], name.bytes):
                return true
            index += 1
        return false

    ## Whether the session is logged in.
    pub func is_authenticated() -> bool:
        return self.authenticated

    ## Whether a mailbox is selected.
    pub func is_selected() -> bool:
        return self.has_selected

    ## Whether the connection is protected by TLS.
    pub func is_secure() -> bool:
        return self.link.is_secure()

    ## The server's text from the last failure, for showing the user.
    pub func text() -> str:
        return (str)self.last_text.view()

    # mark: running commands =====================================================================

    ## Run a command with no arguments that collects nothing.
    func simple(name: str) -> !:
        self.command.clear()
        try self.command.raw(name)
        try self.run(Collect.nothing)

    ## Run the command in `self.command`, collecting `collect`, until its completion.
    func run(collect: Collect) -> !:
        self.collect = collect
        self.command.literal_plus = self.has("LITERAL+")
        self.tag_number += 1
        var tag: collections.Buffer
        defer tag.destroy()
        try tag.put_byte('a')
        try put_decimal(&tag, self.tag_number)
        var line: collections.Buffer
        defer line.destroy()
        try line.put(tag.view())
        try line.put_byte(' ')
        let text = self.command.text.view()
        var sent: usize = 0
        for cut in self.command.cuts.view():
            try line.put(text[sent..<(usize)cut])
            try self.link.write(line.view())
            line.clear()
            sent = cut
            # The server says `+` before a synchronizing literal's bytes, or refuses.
            if not try self.await_continuation(tag.view()):
                return
        try line.put(text[sent..])
        try line.put(b"\r\n")
        try self.link.write(line.view())
        self.sasl_sent = false
        while true:
            let raw = try self.reader.read(&self.link)
            try self.response.parse(raw)
            if self.response.is_continuation():
                # Only SASL asks to go on after the whole command was sent.
                if self.sasl.length() > 0 and not self.sasl_sent:
                    try self.sasl.put(b"\r\n")
                    try self.link.write(self.sasl.view())
                    self.sasl_sent = true
                else:
                    try self.link.write(b"\r\n")
                continue
            if self.response.is_untagged():
                try self.absorb()
                continue
            if self.response.tag != tag.view():
                continue
            try self.complete()
            return

    ## Wait for the continuation request before a literal's bytes: true to send them,
    ## false when the command completed instead (it failed, which `complete` reports).
    func await_continuation(tag: const u8[]) -> bool!:
        while true:
            let raw = try self.reader.read(&self.link)
            try self.response.parse(raw)
            if self.response.is_continuation():
                return true
            if self.response.is_untagged():
                try self.absorb()
                continue
            if self.response.tag == tag:
                try self.complete()
                error(protocol, "the server completed a command before its literal")

    ## Finish the command whose tagged completion is the current response.
    func complete() -> !:
        try self.code()
        self.collect = Collect.nothing
        match self.response.status:
            .ok: return
            .no:
                try self.keep_text()
                error(rejected, self.text())
            .bad:
                try self.keep_text()
                error(bad_command, self.text())
            _: error(protocol, "a command completed without a status")

    ## Keep the current response's text in `last_text`, printable ASCII only.
    func keep_text() -> !:
        self.last_text.clear()
        for byte in self.response.text:
            try self.last_text.put_byte(byte if byte >= 0x20 and byte < 0x7F else '?')
        if self.last_text.length() == 0:
            try self.last_text.put_text("the server gave no reason")

    # mark: untagged responses ===================================================================

    ## Take in the current untagged response.
    func absorb() -> !:
        let response = &self.response
        if response.status != Status.data:
            try self.code()
            if response.status == Status.bye:
                try self.keep_text()
            elif response.status != Status.ok and response.status != Status.preauth:
                try self.keep_text()
            return
        if response.is("CAPABILITY"):
            try self.learn_capabilities(response.values)
        elif response.is("EXISTS"):
            self.selected.exists = response.number else 0
            self.exists_changed = true
        elif response.is("RECENT"):
            self.selected.recent = response.number else 0
        elif response.is("EXPUNGE"):
            if let number = response.number:
                try self.expunged.append(number)
                if self.selected.exists > 0:
                    self.selected.exists -= 1
                self.exists_changed = true
        elif response.is("FETCH"):
            let fetched = try self.read_fetch()
            if self.collect == Collect.messages:
                try self.message_list.append(fetched)
            else:
                try self.changes.append(fetched)
        elif response.is("LIST") or response.is("LSUB"):
            if self.collect == Collect.mailboxes:
                try self.read_list()
        elif response.is("STATUS"):
            if self.collect == Collect.status:
                self.read_status()
        elif response.is("SEARCH"):
            if self.collect == Collect.search:
                var node = response.first(response.values)
                while let value = node:
                    if let number = response.number_of(value):
                        try self.found.append(u32(number))
                    node = response.next(value)
        elif response.is("ESEARCH"):
            if self.collect == Collect.search:
                try self.read_esearch()
        elif response.is("ENABLED"):
            var node = response.first(response.values)
            while let value = node:
                if response.is_atom(value, "UTF8=ACCEPT"):
                    self.command.utf8 = true
                node = response.next(value)

    ## Replace the capabilities with the atoms in list `node`.
    func learn_capabilities(node: usize) -> !:
        self.capabilities.clear()
        try self.capabilities.put_byte(' ')
        var current = self.response.first(node)
        while let value = current:
            for byte in self.response.bytes(value):
                try self.capabilities.put_byte(byte - 32 if byte >= 'a' and byte <= 'z' else byte)
            try self.capabilities.put_byte(' ')
            current = self.response.next(value)

    ## Take in the current status response's code: `[UIDVALIDITY 3]`, `[CAPABILITY …]`.
    func code() -> !:
        let response = &self.response
        let code = response.code
        if code.length == 0:
            return
        let first = response.first(response.code_values)
        var number: u64 = 0
        if let node = first:
            number = response.number_of(node) else 0
        if same(code, b"CAPABILITY"):
            try self.learn_capabilities(response.code_values)
        elif same(code, b"UIDVALIDITY"):
            self.selected.uid_validity = u32(number)
        elif same(code, b"UIDNEXT"):
            self.selected.uid_next = u32(number)
        elif same(code, b"HIGHESTMODSEQ"):
            self.selected.highest_modseq = number
        elif same(code, b"UNSEEN"):
            self.selected.first_unseen = u32(number)
        elif same(code, b"READ-ONLY"):
            self.selected.read_only = true
        elif same(code, b"READ-WRITE"):
            self.selected.read_only = false
        elif same(code, b"APPENDUID"):
            if let second = response.at(response.code_values, 1):
                self.appended = u32(response.number_of(second) else 0)
        elif same(code, b"ALERT"):
            try self.keep_text()

    # mark: events ===============================================================================

    ## Whether anything happened to the selected mailbox since the last `take_events`:
    ## new messages, expunges or flag changes.
    pub func has_events() -> bool:
        return self.exists_changed or self.expunged.length() > 0 or self.changes.length() > 0

    ## Sequence numbers expunged since the last `take_events`, in the order the server
    ## sent them (each counted after the ones before it were removed).
    pub func expunges() -> const u32[]:
        return self.expunged.view()

    ## Messages whose flags changed since the last `take_events`.
    pub func flag_changes() -> const Fetched[]:
        return self.changes.view()

    ## Forget the events.
    pub func take_events():
        self.expunged.clear()
        self.changes.clear()
        self.exists_changed = false

    # mark: login and logout =====================================================================

    ## Log in with a user name and password: SASL PLAIN when offered, LOGIN otherwise.
    pub func login(user: str, password: str) -> !:
        if self.authenticated:
            return
        if self.has("AUTH=PLAIN"):
            var answer: collections.Buffer
            defer answer.destroy()
            try answer.put_byte(0)
            try answer.put_text(user)
            try answer.put_byte(0)
            try answer.put_text(password)
            try self.authenticate("PLAIN", answer.view())
            return
        if self.has("LOGINDISABLED"):
            error(unsupported, "the server refuses LOGIN on this connection")
        self.command.clear()
        try self.command.raw("LOGIN ")
        try self.command.astring(user.bytes)
        try self.command.raw(" ")
        try self.command.astring(password.bytes)
        self.run(Collect.nothing) catch failure:
            if failure.code == rejected:
                error(authentication, self.text())
            error(failure.code, failure.message)
        try self.after_login()

    ## Log in with an OAuth 2 access token (SASL XOAUTH2, as Gmail and Outlook use).
    pub func login_oauth(user: str, token: str) -> !:
        if not self.has("AUTH=XOAUTH2"):
            error(unsupported, "the server does not offer XOAUTH2")
        var answer: collections.Buffer
        defer answer.destroy()
        try answer.put(b"user=")
        try answer.put_text(user)
        try answer.put(b"\x01auth=Bearer ")
        try answer.put_text(token)
        try answer.put(b"\x01\x01")
        try self.authenticate("XOAUTH2", answer.view())

    ## Run AUTHENTICATE `mechanism` with the SASL answer `answer`.
    func authenticate(mechanism: str, answer: const u8[]) -> !:
        self.command.clear()
        self.sasl.clear()
        try self.command.raw("AUTHENTICATE ")
        try self.command.raw(mechanism)
        var encoded: collections.Buffer
        defer encoded.destroy()
        try put_base64(answer, &encoded)
        if self.has("SASL-IR"):
            try self.command.raw(" ")
            try self.command.text.put(encoded.view())
            self.sasl_sent = true
        else:
            try self.sasl.put(encoded.view())
        defer self.sasl.clear()
        self.run(Collect.nothing) catch failure:
            if failure.code == rejected:
                error(authentication, self.text())
            error(failure.code, failure.message)
        try self.after_login()

    func after_login() -> !:
        self.authenticated = true
        if self.capabilities.length() == 0 or not self.has("IMAP4REV1") and not self.has("IMAP4REV2"):
            try self.simple("CAPABILITY")
        if self.has("UTF8=ACCEPT") and self.has("ENABLE"):
            try self.simple("ENABLE UTF8=ACCEPT")

    ## Ask the server for news (NOOP): new messages, expunges and flag changes arrive as
    ## events.
    pub func noop() -> !:
        try self.simple("NOOP")

    ## Say goodbye and close the connection. Failures are ignored: the connection goes.
    pub func logout():
        if self.link.is_open():
            self.simple("LOGOUT") catch failure:
                recover ()
        self.close()

    ## Close the connection and give everything back.
    pub func close():
        self.link.close()
        self.reader.close()
        self.response.close()
        self.command.close()
        self.capabilities.destroy()
        self.last_text.destroy()
        self.sasl.destroy()
        self.pool.destroy()
        self.mailbox_list.destroy()
        self.message_list.destroy()
        self.found.destroy()
        self.expunged.destroy()
        self.changes.destroy()
        self.idle_tag.destroy()

    ## Forget the last command's results before a new one collects.
    func reset_results():
        self.pool.destroy()
        self.mailbox_list.clear()
        self.message_list.clear()
        self.found.clear()
        self.status_result = MailboxStatus()
        self.appended = 0