net.smtp sends mail but nothing in vlib reads it, so a V program that wants to look at a mailbox has to shell out or reimplement IMAP. This adds net.imap, a client for IMAP4rev1 (RFC 3501).

I checked vpm and awesome-v first: there is no IMAP module in either.

mut c := imap.new_client(
    server:   'imap.example.com'
    username: 'someone@example.com'
    password: 'hunter2'
    ssl:      true
)!
defer { c.close() or {} }

inbox := c.select_mailbox('INBOX')!
println('${inbox.exists} messages, ${inbox.recent} recent')

unread := c.search('UNSEEN')!
for msg in c.fetch(unread, '(UID ENVELOPE)')! {
    if envelope := msg.envelope {
        println('${envelope.from[0].addr()}: ${envelope.subject}')
    }
}

Responses are tokenised, not searched

The module reads the grammar of RFC 3501 section 9 rather than looking for keywords in a response line. That is not tidiness, it is correctness: a message whose subject is UID 999 answers a search for UID exactly as well as the real field does, and a body containing ) ends a response that a bracket-counting parser would still be reading.

wire.v is a decoder over the four shapes the protocol is built from: atoms, quoted strings, literals and parenthesised lists. It reads the connection directly with one octet of lookahead, so a literal is taken by count and its content is never offered back to the parser. An item this module does not model is stepped over whole by skip_value, so a server extension cannot desynchronise the rest of the response.

Two grammar details worth naming, because both are easy to get wrong and both are covered by tests:

• env-cc = "(" 1*address ")". The addresses in an envelope are concatenated with nothing between them, not separated by spaces like every other list in the protocol.
• [ is a valid ATOM-CHAR; only ] is excluded. Reading a fetch item name with a plain atom reader therefore swallows the opening bracket of BODY[] and leaves the rest unreadable.

Mailbox names

Names are ordinary UTF-8 in the API and travel as the modified UTF-7 of section 5.1.3, encoded on the way out and decoded on the way in. Without it, list_mailboxes hands back &AMk-l&AOk-ments where the user's mailbox is called Éléments. The encoding is checked against the two examples printed in the RFC and cross-checked against an independent implementation.

Sequence sets

SeqSet keeps message numbers as merged ranges, so a search matching fifty thousand messages is sent as FETCH 1:50000 .... A comma separated list of every number would be a command line no server is obliged to accept.

What is implemented

CAPABILITY, NOOP, LOGOUT, STARTTLS, AUTHENTICATE PLAIN, LOGIN, SELECT, EXAMINE, CREATE, DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, STATUS, APPEND, CHECK, CLOSE, UNSELECT, EXPUNGE, SEARCH, FETCH, STORE, COPY, MOVE, and the UID forms of the last five.

FETCH parses UID, FLAGS, RFC822.SIZE, INTERNALDATE, ENVELOPE, BODYSTRUCTURE and any number of BODY[...] sections, keyed by the specification the server echoed back.

Some things that took deliberate handling:

• An argument a quoted string cannot hold, an eight bit password or a message body, is sent as a literal: the introducer goes out, the client waits for the + continuation, then the octets follow. Section 2.2.1 says the server may send untagged data or reject the command instead of continuing, so the wait handles both rather than assuming the next line is the +.
• A mailbox changes under a client at any moment, and the server says so by slipping EXISTS, EXPUNGE and FETCH responses into whatever command happens to be in flight. Those are collected rather than discarded, and Client.exists and Client.recent follow them.
• A completion carrying a tag other than the outstanding one is an error. It means the client and the server disagree about which command is running, and nothing later recovers from that.
• A literal announces its own length, so a server can ask a client to allocate as much memory as it likes. There is a cap, checked before the allocation.
• An untagged BYE closes the session, and a greeting that turns the connection away closes the socket rather than leaving the server to time it out.

ESEARCH (RFC 4731) and MOVE (RFC 6851) are supported; supports() is there to guard the optional ones.

Tests

Four files, 513 assertions, no external server needed.

• utf7_test.v covers the RFC's own examples, a round trip over Japanese, Russian, Chinese, French and an emoji, the astral plane surrogate pair, and six malformed inputs that must be refused.
• seqset_test.v covers merging, ordering, *, parsing and the fifty thousand message case.
• response_test.v runs the response reader over transcripts taken from the RFC, including its envelope and body structure examples, plus the two traps above: a body and an envelope subject that both read like protocol.
• imap_test.v drives the client over a real socket against a scripted server, checking the exact bytes each command puts on the wire, the literal handshake for APPEND and for an eight bit password, and that an unsolicited EXISTS reaches the client.

v fmt -verify and v vet -W are clean on all nine files, and none of them show up in v test-cleancode.