Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-smtp

Source of release 0.6.0

0.6.0 / src / smtp / client.lucb

#==============================================================================================
#
#   smtp/client - Connecting, EHLO, STARTTLS, AUTH and replies
#
#   DESCRIPTION:
#       A reply is one or more lines with the same three-digit code, all but the last
#       written `250-…`, the last `250 …`. The client keeps the last reply's code and its
#       text (the lines joined by newlines) for the caller. EHLO's reply lists the
#       extensions, one keyword a line with its parameters (`SIZE 35882577`,
#       `AUTH PLAIN LOGIN XOAUTH2`); they are kept upper-cased for `has` and
#       `parameters`. A 4xx reply fails with `deferred`, a 5xx with `rejected`.
#
#==============================================================================================

## The default time any one read or write may take.
pub let default_timeout: u64 = 60 * 1000000000

## The longest reply accepted, all its lines together.
let maximum_reply: usize = 65536

## How the connection is protected.
pub enum Security as u8:
    ## No TLS: only for a local test server.
    plain = 0
    ## Plain at first, upgraded by STARTTLS before AUTH (port 587).
    starttls = 1
    ## TLS from the first byte (port 465).
    tls = 2

## The ASCII upper case of `byte`.
func upper(byte: u8) -> u8:
    return byte - 32 if byte >= 'a' and byte <= 'z' else byte

## Whether `a` and `b` are equal ignoring ASCII case.
func same(a: const u8[], b: const u8[]) -> bool:
    if a.length != b.length:
        return false
    for index in 0..<a.length:
        if upper(a[index]) != upper(b[index]):
            return false
    return true

## A connection to one submission server.
pub struct Client:
    var stream: tls_stream.Stream
    ## Nanoseconds any one read or write may take.
    pub var timeout: u64
    var cancellation: sync.Cancellation*?
    var connected: bool
    var input: Bytes
    var input_start: usize
    ## The EHLO extension lines after the first, upper-cased, each ending in a newline.
    var extensions: Bytes
    var reply_code: u16
    var reply_text: Bytes
    ## Recipients the last `send` refused, each ending in a newline.
    var refused_text: Bytes
    var refused_total: usize

    ## Connect to `host` on `port`, read the greeting, say EHLO as `name` and upgrade
    ## with STARTTLS when `security` asks for it.
    pub static func open(host: str, port: u16, security: Security, name: str = "localhost", timeout: u64 = default_timeout, cancellation: sync.Cancellation*? = none, trust: tls_stream.Trust = tls_stream.Trust()) -> Client!:
        let stream = try tls_stream.Stream.connect(host, port, security == Security.tls, try net.Deadline.after(timeout), cancellation, policy = trust)
        var client = Client(stream = stream, timeout = timeout, cancellation = cancellation, connected = true)
        errdefer client.close()
        try client.greet(name)
        if security == Security.starttls:
            if not client.has("STARTTLS"):
                error(unsupported, "the server does not offer STARTTLS")
            try client.expect(b"STARTTLS", 2)
            if client.input_start < client.input.used:
                error(protocol, "the server sent data after its STARTTLS answer")
            client.stream.set_deadline(try net.Deadline.after(timeout), cancellation)
            try client.stream.start_tls(host, trust)
            try client.hello(name)
        return client

    ## A client over an already connected, plain `connection` (tests).
    pub static func over(connection: net.Connection, name: str = "localhost", timeout: u64 = default_timeout) -> Client!:
        var client = Client(stream = tls_stream.Stream.plain(connection), timeout = timeout, connected = true)
        errdefer client.close()
        try client.greet(name)
        return client

    ## Read the greeting and say EHLO.
    func greet(name: str) -> !:
        try self.read_reply()
        if self.reply_code != 220:
            try self.fail("the server's greeting")
        try self.hello(name)

    ## Say EHLO as `name` and learn the extensions; fall back to HELO.
    func hello(name: str) -> !:
        var line: Bytes
        defer line.close()
        try line.put(b"EHLO ")
        try line.text(name)
        let code = try self.command(line.view())
        if code // 100 != 2:
            line.clear()
            try line.put(b"HELO ")
            try line.text(name)
            try self.expect(line.view(), 2)
            self.extensions.clear()
            return
        self.extensions.clear()
        let text = self.reply_text.view()
        # The first line names the server; each later one is an extension.
        var index: usize = 0
        while index < text.length and text[index] != '\n':
            index += 1
        index += 1
        while index < text.length:
            try self.extensions.byte(upper(text[index]))
            index += 1
        if self.extensions.used > 0:
            try self.extensions.byte('\n')

    ## Whether the server offers extension `keyword` (`STARTTLS`, `SIZE`), ignoring case.
    pub func has(keyword: str) -> bool:
        return self.extension(keyword) != none

    ## The parameters of extension `keyword`, upper-cased (`PLAIN LOGIN` for AUTH), or
    ## none when it is not offered.
    pub func extension(keyword: str) -> const u8[]?:
        let data = self.extensions.view()
        var start: usize = 0
        while start < data.length:
            var end = start
            while end < data.length and data[end] != '\n':
                end += 1
            var word_end = start
            while word_end < end and data[word_end] != ' ' and data[word_end] != '=':
                word_end += 1
            if same(data[start..<word_end], keyword.bytes):
                return data[(word_end + 1 if word_end < end else end)..<end]
            start = end + 1
        return none

    ## Whether authentication method `mechanism` is offered.
    pub func offers(mechanism: str) -> bool:
        let methods = self.extension("AUTH") else return false
        var start: usize = 0
        while start < methods.length:
            var end = start
            while end < methods.length and methods[end] != ' ':
                end += 1
            if same(methods[start..<end], mechanism.bytes):
                return true
            start = end + 1
        return false

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

    ## The code of the last reply.
    pub func code() -> u16:
        return self.reply_code

    ## The text of the last reply, its lines joined by newlines.
    pub func text() -> str:
        return (str)self.reply_text.view()

    # mark: replies ==============================================================================

    ## Read one reply into `reply_code` and `reply_text`.
    func read_reply() -> !:
        self.reply_text.clear()
        while true:
            let line = try self.read_line()
            if line.length < 3:
                error(protocol, "a reply line too short to hold a code")
            var code: u16 = 0
            for digit in line[0..<3]:
                if digit < '0' or digit > '9':
                    error(protocol, "a reply without a numeric code")
                code = code * 10 + (u16)(digit - '0')
            self.reply_code = code
            if self.reply_text.used > 0:
                try self.reply_text.byte('\n')
            for byte in line[(4 if line.length > 4 else line.length)..]:
                try self.reply_text.byte(byte if byte >= 0x20 and byte < 0x7F else '?')
            if self.reply_text.used > maximum_reply:
                error(limit_exceeded, "the reply is too long")
            if line.length == 3 or line[3] != '-':
                return

    ## The next line without its line end, valid until the next read.
    func read_line() -> const u8[]!:
        var searched: usize = 0
        while true:
            let data = self.input.view()
            var index = self.input_start + searched
            while index < data.length and data[index] != '\n':
                index += 1
            if index < data.length:
                var end = index
                if end > self.input_start and data[end - 1] == '\r':
                    end -= 1
                let line = data[self.input_start..<end]
                self.input_start = index + 1
                return line
            searched = data.length - self.input_start
            if searched > maximum_reply:
                error(limit_exceeded, "a reply line is too long")
            try self.fill()

    ## Read more from the server, first moving unread bytes to the front.
    func fill() -> !:
        if not self.connected:
            error(disconnected, "the connection is closed")
        if self.input_start > 0:
            let unread = self.input.used - self.input_start
            memory.move(self.input.data, self.input.data[self.input_start..], unread)
            self.input.used = unread
            self.input_start = 0
        try self.input.reserve(4096)
        let count = try self.stream.read_within(self.input.data[self.input.used..], try net.Deadline.after(self.timeout), self.cancellation)
        if count == 0:
            error(disconnected, "the server closed the connection")
        self.input.used += count

    ## Write `data` as it is.
    func write(data: const u8[]) -> !:
        if not self.connected:
            error(disconnected, "the connection is closed")
        try self.stream.write_within(data, try net.Deadline.after(self.timeout), self.cancellation)

    ## Send `line` with CRLF and read the reply; its code.
    func command(line: const u8[]) -> u16!:
        var out: Bytes
        defer out.close()
        try out.put(line)
        try out.put(b"\r\n")
        try self.write(out.view())
        try self.read_reply()
        return self.reply_code

    ## Send `line` and fail unless the reply's code is in class `expected` (2 or 3).
    func expect(line: const u8[], expected: u16) -> !:
        if try self.command(line) // 100 != expected:
            try self.fail("the server refused")

    ## Fail with the last reply: deferred for 4xx, rejected for 5xx.
    func fail(context: str) -> !:
        if self.reply_text.used == 0:
            try self.reply_text.text(context)
        if self.reply_code // 100 == 4:
            error(deferred, self.text())
        error(rejected, self.text())

    # mark: authentication =======================================================================

    ## Authenticate with a user name and password: AUTH PLAIN, else AUTH LOGIN.
    pub func login(user: str, password: str) -> !:
        var answer: Bytes
        defer answer.close()
        var line: Bytes
        defer line.close()
        if self.offers("PLAIN"):
            try answer.byte(0)
            try answer.text(user)
            try answer.byte(0)
            try answer.text(password)
            try line.put(b"AUTH PLAIN ")
            try put_base64(answer.view(), &line)
            try self.finish_auth(try self.command(line.view()))
            return
        if self.offers("LOGIN"):
            if try self.command(b"AUTH LOGIN") != 334:
                try self.fail("AUTH LOGIN")
            try put_base64(user.bytes, &line)
            if try self.command(line.view()) != 334:
                try self.finish_auth(self.reply_code)
                return
            line.clear()
            try put_base64(password.bytes, &line)
            try self.finish_auth(try self.command(line.view()))
            return
        error(unsupported, "the server offers no password authentication")

    ## Authenticate with an OAuth 2 access token (AUTH XOAUTH2).
    pub func login_oauth(user: str, token: str) -> !:
        if not self.offers("XOAUTH2"):
            error(unsupported, "the server does not offer XOAUTH2")
        var answer: Bytes
        defer answer.close()
        try answer.put(b"user=")
        try answer.text(user)
        try answer.put(b"\x01auth=Bearer ")
        try answer.text(token)
        try answer.put(b"\x01\x01")
        var line: Bytes
        defer line.close()
        try line.put(b"AUTH XOAUTH2 ")
        try put_base64(answer.view(), &line)
        var code = try self.command(line.view())
        if code == 334:
            # The server explains the failure in a challenge; an empty answer ends it.
            code = try self.command(b"")
        try self.finish_auth(code)

    ## Check the completion of AUTH: 235 is success, anything else a failure.
    func finish_auth(code: u16) -> !:
        if code == 235:
            return
        if code // 100 == 5:
            error(authentication, self.text())
        try self.fail("authentication")

    # mark: closing ==============================================================================

    ## Say goodbye and close; failures are ignored, the connection goes either way.
    pub func quit():
        if self.connected:
            _ = self.command(b"QUIT") catch failure:
                recover 0
        self.close()

    ## Close the connection and give everything back.
    pub func close():
        if self.connected:
            self.stream.close() catch failure:
                self.stream.destroy()
            self.connected = false
        self.input.close()
        self.extensions.close()
        self.reply_text.close()
        self.refused_text.close()