dymokomi/luce-imap
Source of release 0.6.0
0.6.0 / src / imap / response.lucb
#==============================================================================================
#
# imap/response - One response, read off the wire and parsed
#
# DESCRIPTION:
# A response is a line, with literals (`{n}` CRLF and n bytes) inline. The Reader
# buffers what the link delivers and hands out one whole response at a time.
# Response.parse reads it: the tag (`*`, `+` or a command's), then either a status
# (OK, NO, BAD, BYE, PREAUTH) with an optional `[code args]` and its text, or a
# name with data (`* 23 EXISTS`, `* CAPABILITY …`, `* 4 FETCH (…)`). Data values are
# atoms, numbers, strings (quoted or literal), NIL and parenthesised lists, kept as
# a tree of nodes over the response's bytes. Atoms keep a bracketed section whole,
# so `BODY[HEADER.FIELDS (DATE FROM)]<0>` is one atom.
#
#==============================================================================================
## The most nodes one response may hold.
let maximum_nodes: usize = 1 << 22
## What a node is.
pub enum Kind as u8:
atom = 0
number = 1
string = 2
nil = 3
list = 4
## One value of a response: its bytes, or its children.
struct Node:
var kind: Kind
var start: usize
var end: usize
## A quoted string holding backslash escapes.
var escaped: bool
## The first child of a list and the next sibling, as index + 1; zero for none.
var child: u32
var next: u32
var count: u32
## The status a response carries.
pub enum Status as u8:
## Data, not a status: `* 23 EXISTS`, `* LIST …`, a continuation.
data = 0
ok = 1
no = 2
bad = 3
bye = 4
preauth = 5
## A parsed response. Views point into the reader's buffer and the node table; both
## last until the next response is read.
pub struct Response:
var raw: const u8[]
var nodes: collections.List[Node]
pub var tag: const u8[]
pub var status: Status
## The number before the name in `* 23 EXISTS`.
pub var number: u32?
## `OK`, `EXISTS`, `FETCH`, `LIST`, …; empty for a continuation.
pub var name: const u8[]
## The response code (`UIDVALIDITY`) and the list node of its arguments.
pub var code: const u8[]
pub var code_values: usize
## Human-readable text after a status or a continuation.
pub var text: const u8[]
## The list node holding the data after the name.
pub var values: usize
## Whether this is a continuation request, `+ …`.
pub func is_continuation() -> bool:
return self.tag.length == 1 and self.tag[0] == '+'
## Whether this is untagged, `* …`.
pub func is_untagged() -> bool:
return self.tag.length == 1 and self.tag[0] == '*'
## Whether the name is `name`, ignoring case.
pub func is(name: str) -> bool:
return same(self.name, name.bytes)
# mark: nodes ================================================================================
## The kind of node `node`.
pub func kind(node: usize) -> Kind:
return self.nodes.at(node).kind
## The first child of list `node`, or none.
pub func first(node: usize) -> usize?:
let child = self.nodes.at(node).child
return none if child == 0 else (usize)child - 1
## The node after `node` in its list, or none.
pub func next(node: usize) -> usize?:
let sibling = self.nodes.at(node).next
return none if sibling == 0 else (usize)sibling - 1
## The child at `index` of list `node`, or none.
pub func at(node: usize, index: usize) -> usize?:
var current = self.first(node)
var step: usize = 0
while let child = current:
if step == index:
return child
current = self.next(child)
step += 1
return none
## How many children list `node` has.
pub func count(node: usize) -> usize:
return self.nodes.at(node).count
## The bytes of an atom, number or string node; a quoted string as written, escapes
## and all (see `string`).
pub func bytes(node: usize) -> const u8[]:
return self.raw[self.nodes.at(node).start..<self.nodes.at(node).end]
## Append string, atom or number `node`'s text, unescaped; NIL appends nothing.
pub func string(node: usize, out: collections.Buffer*) -> !:
let entry = self.nodes.at(node)
if entry.kind == Kind.nil or entry.kind == Kind.list:
return
let data = self.raw[entry.start..<entry.end]
if not entry.escaped:
try out.put(data)
return
var index: usize = 0
while index < data.length:
if data[index] == '\\' and index + 1 < data.length:
index += 1
try out.put_byte(data[index])
index += 1
## The value of a number node, or none for anything else.
pub func number_of(node: usize) -> u64?:
if self.nodes.at(node).kind != Kind.number:
return none
var value: u64 = 0
for digit in self.bytes(node):
value = (value *? 10 else return none) +? (u64)(digit - '0') else return none
return value
## Whether node `node` is the atom `name`, ignoring case.
pub func is_atom(node: usize, name: str) -> bool:
return self.nodes.at(node).kind == Kind.atom and same(self.bytes(node), name.bytes)
# mark: parsing ==============================================================================
func add(kind: Kind, start: usize, end: usize) -> usize!:
if self.nodes.length() >= maximum_nodes:
error(limit_exceeded, "the response has too many values")
try self.nodes.append(Node(kind = kind, start = start, end = end, escaped = false, child = 0, next = 0, count = 0))
return self.nodes.length() - 1
## Make `child` the last child of list `list`, after `last` (none when it is first).
func link(list: usize, last: usize?, child: usize):
if let previous = last:
self.nodes.items()[previous].next = u32(child + 1)
else:
self.nodes.items()[list].child = u32(child + 1)
self.nodes.items()[list].count += 1
## Parse `raw`, one whole response with its CRLF. Views point into `raw`.
pub func parse(raw: const u8[]) -> !:
self.raw = raw
self.nodes.clear()
self.status = Status.data
self.number = none
var empty: const u8[]
self.tag = empty
self.name = empty
self.code = empty
self.text = empty
self.values = try self.add(Kind.list, 0, 0)
self.code_values = try self.add(Kind.list, 0, 0)
var cursor = Cursor(data = raw, index = 0)
self.tag = cursor.word()
if self.tag.length == 0:
error(protocol, "a response without a tag")
if self.is_continuation():
cursor.space()
self.text = cursor.rest()
return
cursor.space()
if self.is_untagged() and cursor.digit():
let digits = cursor.word()
var value: u32 = 0
for digit in digits:
if digit < '0' or digit > '9':
error(protocol, "a malformed message number")
value = (value *? 10 else error(protocol, "a message number too large")) + (u32)(digit - '0')
self.number = value
cursor.space()
self.name = cursor.word()
let status = status_of(self.name)
if status != Status.data:
self.status = status
cursor.space()
if cursor.peek() == '[':
cursor.index += 1
self.code = cursor.code_atom()
var last: usize? = none
while true:
cursor.space()
let next = cursor.peek()
if next == ']' or next == 0:
break
let value = try self.value(&cursor, true)
self.link(self.code_values, last, value)
last = value
if cursor.peek() == ']':
cursor.index += 1
cursor.space()
self.text = cursor.rest()
return
var last: usize? = none
while true:
cursor.space()
if cursor.at_end():
break
let value = try self.value(&cursor, false)
self.link(self.values, last, value)
last = value
## Parse the value at the cursor; in a response code `]` ends an atom.
func value(cursor: Cursor*, in_code: bool) -> usize!:
let byte = cursor.peek()
if byte == '(':
cursor.index += 1
let list = try self.add(Kind.list, cursor.index, cursor.index)
var last: usize? = none
while true:
cursor.space()
let next = cursor.peek()
if next == ')':
cursor.index += 1
break
if cursor.at_end():
error(protocol, "a list without its closing parenthesis")
let child = try self.value(cursor, in_code)
self.link(list, last, child)
last = child
self.nodes.items()[list].end = cursor.index
return list
if byte == '"':
cursor.index += 1
let start = cursor.index
var escaped = false
while cursor.index < cursor.data.length and cursor.data[cursor.index] != '"':
if cursor.data[cursor.index] == '\\':
escaped = true
cursor.index += 1
cursor.index += 1
if cursor.index >= cursor.data.length:
error(protocol, "a quoted string without its closing quote")
let node = try self.add(Kind.string, start, cursor.index)
self.nodes.items()[node].escaped = escaped
cursor.index += 1
return node
if byte == '{':
cursor.index += 1
var length: usize = 0
while cursor.index < cursor.data.length and cursor.data[cursor.index] >= '0' and cursor.data[cursor.index] <= '9':
length = (length *? 10 else error(protocol, "a literal too large")) + (usize)(cursor.data[cursor.index] - '0')
cursor.index += 1
if cursor.index < cursor.data.length and cursor.data[cursor.index] == '+':
cursor.index += 1
if not cursor.expect(b"}\r\n"):
error(protocol, "a malformed literal")
let start = cursor.index
if length > cursor.data.length - start:
error(protocol, "a literal longer than the response")
cursor.index += length
return try self.add(Kind.string, start, start + length)
let atom = cursor.atom(in_code)
if atom.length == 0:
error(protocol, "an unexpected character in a response")
let start = cursor.index - atom.length
if same(atom, b"NIL"):
return try self.add(Kind.nil, start, cursor.index)
var digits = true
for digit in atom:
if digit < '0' or digit > '9':
digits = false
return try self.add(Kind.number if digits else Kind.atom, start, cursor.index)
## Give the node table back.
pub func close():
self.nodes.destroy()
## The status named `name`, or none.
func status_of(name: const u8[]) -> Status:
if same(name, b"OK"):
return Status.ok
if same(name, b"NO"):
return Status.no
if same(name, b"BAD"):
return Status.bad
if same(name, b"BYE"):
return Status.bye
if same(name, b"PREAUTH"):
return Status.preauth
return Status.data
## A position in a response's bytes.
struct Cursor:
var data: const u8[]
var index: usize
## The byte at the cursor; zero at the end of the line.
func peek() -> u8:
if self.index >= self.data.length:
return 0
let byte = self.data[self.index]
return 0 if byte == '\r' or byte == '\n' else byte
func at_end() -> bool:
return self.peek() == 0
func digit() -> bool:
let byte = self.peek()
return byte >= '0' and byte <= '9'
## Skip spaces.
func space():
while self.index < self.data.length and self.data[self.index] == ' ':
self.index += 1
## Take `text` when it is next.
func expect(text: const u8[]) -> bool:
if self.data.length - self.index >= text.length:
for offset in 0..<text.length:
if self.data[self.index + offset] != text[offset]:
return false
self.index += text.length
return true
return false
## The run up to the next space or line end.
func word() -> const u8[]:
let start = self.index
while self.peek() != 0 and self.peek() != ' ':
self.index += 1
return self.data[start..<self.index]
## A response code's name: up to a space or `]`.
func code_atom() -> const u8[]:
let start = self.index
while self.peek() != 0 and self.peek() != ' ' and self.peek() != ']':
self.index += 1
return self.data[start..<self.index]
## An atom: up to a space, a parenthesis or the line end, with a bracketed section
## (which may hold spaces) kept whole. In a response code `]` ends it.
func atom(in_code: bool) -> const u8[]:
let start = self.index
var depth: usize = 0
while true:
let byte = self.peek()
if byte == 0:
break
if depth == 0 and (byte == ' ' or byte == '(' or byte == ')' or byte == '"' or byte == '{'):
break
if byte == '[':
depth += 1
elif byte == ']':
if depth == 0:
if in_code:
break
else:
depth -= 1
self.index += 1
return self.data[start..<self.index]
## The rest of the line.
func rest() -> const u8[]:
let start = self.index
while self.peek() != 0:
self.index += 1
return self.data[start..<self.index]
## Buffers what the link delivers and hands out whole responses.
pub struct Reader:
var buffer: collections.Buffer
## Where the unread bytes start in the buffer.
var start: usize
## The last response read: its line and literals.
var current: collections.Buffer
## Read one whole response from `link` into `current`.
pub func read(link: Link*) -> const u8[]!:
self.current.clear()
while true:
let line_start = self.current.length()
try self.line(link)
let line = self.current.view()[line_start..]
# A line ending `{n}` or `{n+}` is followed by n bytes, then more line.
let length = literal_length(line) else return self.current.view()
try self.exactly(link, length)
## Append one line, CRLF included, to `current`.
func line(link: Link*) -> !:
# Bytes after `start` already searched for the line end.
var searched: usize = 0
while true:
let data = self.buffer.view()
var index = self.start + searched
while index < data.length and data[index] != '\n':
index += 1
if index < data.length:
try self.current.put(data[self.start..<index + 1])
self.start = index + 1
if self.current.length() > maximum_line + maximum_literal:
error(limit_exceeded, "the response is too long")
return
searched = data.length - self.start
if searched > maximum_line:
error(limit_exceeded, "a response line is too long")
try self.fill(link)
## Append exactly `count` bytes to `current`.
func exactly(link: Link*, count: usize) -> !:
if count > maximum_literal:
error(limit_exceeded, "a literal is larger than this client accepts")
var remaining = count
while remaining > 0:
let available = self.buffer.length() - self.start
if available == 0:
try self.fill(link)
continue
let take = available if available < remaining else remaining
try self.current.put(self.buffer.view()[self.start..<self.start + take])
self.start += take
remaining -= take
## Read more from `link`, first dropping the bytes already handed out.
func fill(link: Link*) -> !:
if self.start > 0:
self.buffer.remove(0, self.start)
self.start = 0
var chunk: u8[16384]
let count = try link.read(chunk[0..])
if count == 0:
error(disconnected, "the server closed the connection")
try self.buffer.put(chunk[0..<count])
## Whether bytes are waiting that were read but not handed out.
pub func pending() -> bool:
return self.start < self.buffer.length()
## Give the buffers back.
pub func close():
self.buffer.destroy()
self.current.destroy()
self.start = 0
## The length a line's trailing literal marker announces (`{12}` or `{12+}` before CRLF),
## or none.
func literal_length(line: const u8[]) -> usize?:
var end = line.length
if end > 0 and line[end - 1] == '\n':
end -= 1
if end > 0 and line[end - 1] == '\r':
end -= 1
if end < 3 or line[end - 1] != '}':
return none
var index = end - 1
if line[index - 1] == '+':
index -= 1
var length: usize = 0
var scale: usize = 1
var digits: usize = 0
while index > 0 and line[index - 1] >= '0' and line[index - 1] <= '9':
index -= 1
length += (usize)(line[index] - '0') * scale
scale *= 10
digits += 1
if digits > 10:
return none
if digits == 0 or index == 0 or line[index - 1] != '{':
return none
return length