1/*
2Package imapclient provides an IMAP4 client implementing IMAP4rev1 (RFC 3501),
3IMAP4rev2 (RFC 9051) and various extensions.
4
5Warning: Currently primarily for testing the mox IMAP4 server. Behaviour that
6may not be required by the IMAP4 specification may be expected by this client.
7
8See [Conn] for a high-level client for executing IMAP commands. Use its embedded
9[Proto] for lower-level writing of commands and reading of responses.
10*/
11package imapclient
12
13import (
14 "bufio"
15 "crypto/tls"
16 "fmt"
17 "io"
18 "log/slog"
19 "net"
20 "strings"
21
22 "github.com/mjl-/mox/mlog"
23 "github.com/mjl-/mox/moxio"
24)
25
26// Conn is an connection to an IMAP server.
27//
28// Method names on Conn are the names of IMAP commands. CloseMailbox, which
29// executes the IMAP CLOSE command, is an exception. The Close method closes the
30// connection.
31//
32// The methods starting with MSN are the original (old) IMAP commands. The variants
33// starting with UID should almost always be used instead, if available.
34//
35// The methods on Conn typically return errors of type Error or Response. Error
36// represents protocol and i/o level errors, including io.ErrDeadlineExceeded and
37// various errors for closed connections. Response is returned as error if the IMAP
38// result is NO or BAD instead of OK. The responses returned by the IMAP command
39// methods can also be non-zero on errors. Callers may wish to process any untagged
40// responses.
41//
42// The IMAP command methods defined on Conn don't interpret the untagged responses
43// except for untagged CAPABILITY and untagged ENABLED responses, and the
44// CAPABILITY response code. Fields CapAvailable and CapEnabled are updated when
45// those untagged responses are received.
46//
47// Capabilities indicate which optional IMAP functionality is supported by a
48// server. Capabilities are typically implicitly enabled when the client sends a
49// command using syntax of an optional extension. Extensions without new syntax
50// from client to server, but with new behaviour or syntax from server to client,
51// the client needs to explicitly enable the capability with the ENABLE command,
52// see the Enable method.
53type Conn struct {
54 // If true, server sent a PREAUTH tag and the connection is already authenticated,
55 // e.g. based on TLS certificate authentication.
56 Preauth bool
57
58 // Capabilities available at server, from CAPABILITY command or response code.
59 CapAvailable []Capability
60 // Capabilities marked as enabled by the server, typically after an ENABLE command.
61 CapEnabled []Capability
62
63 // Proto provides lower-level functions for interacting with the IMAP connection,
64 // such as reading and writing individual lines/commands/responses.
65 Proto
66}
67
68// Proto provides low-level operations for writing requests and reading responses
69// on an IMAP connection.
70//
71// To implement the IDLE command, write "IDLE" using [Proto.WriteCommandf], then
72// read a line with [Proto.Readline]. If it starts with "+ ", the connection is in
73// idle mode and untagged responses can be read using [Proto.ReadUntagged]. If the
74// line doesn't start with "+ ", use [ParseResult] to interpret it as a response to
75// IDLE, which should be a NO or BAD. To abort idle mode, write "DONE" using
76// [Proto.Writelinef] and wait until a result line has been read.
77type Proto struct {
78 // Connection, may be original TCP or TLS connection. Reads go through c.br, and
79 // writes through c.xbw. The "x" for the writes indicate that failed writes cause
80 // an i/o panic, which is either turned into a returned error, or passed on (see
81 // boolean panic). The reader and writer wrap a tracing reading/writer and may wrap
82 // flate compression.
83 conn net.Conn
84 connBroken bool // If connection is broken, we won't flush (and write) again.
85 br *bufio.Reader
86 tr *moxio.TraceReader
87 xbw *bufio.Writer
88 compress bool // If compression is enabled, we must flush flateWriter and its target original bufio writer.
89 xflateWriter *moxio.FlateWriter
90 xflateBW *bufio.Writer
91 xtw *moxio.TraceWriter
92
93 log mlog.Log
94 errHandle func(err error) // If set, called for all errors. Can panic. Used for imapserver tests.
95 tagGen int
96 record bool // If true, bytes read are added to recordBuf. recorded() resets.
97 recordBuf []byte
98
99 lastTag string
100}
101
102// Error is a parse or other protocol error.
103type Error struct{ err error }
104
105func (e Error) Error() string {
106 return e.err.Error()
107}
108
109func (e Error) Unwrap() error {
110 return e.err
111}
112
113// Opts has optional fields that influence behaviour of a Conn.
114type Opts struct {
115 Logger *slog.Logger
116
117 // Error is called for IMAP-level and connection-level errors during the IMAP
118 // command methods on Conn, not for errors in calls on Proto. Error is allowed to
119 // call panic.
120 Error func(err error)
121}
122
123// New initializes a new IMAP client on conn.
124//
125// Conn should normally be a TLS connection, typically connected to port 993 of an
126// IMAP server. Alternatively, conn can be a plain TCP connection to port 143. TLS
127// should be enabled on plain TCP connections with the [Conn.StartTLS] method.
128//
129// The initial untagged greeting response is read and must be "OK" or
130// "PREAUTH". If preauth, the connection is already in authenticated state,
131// typically through TLS client certificate. This is indicated in Conn.Preauth.
132//
133// Logging is written to opts.Logger. In particular, IMAP protocol traces are
134// written with prefixes "CR: " and "CW: " (client read/write) as quoted strings at
135// levels Debug-4, with authentication messages at Debug-6 and (user) data at level
136// Debug-8.
137func New(conn net.Conn, opts *Opts) (client *Conn, rerr error) {
138 c := Conn{
139 Proto: Proto{conn: conn},
140 }
141
142 var clog *slog.Logger
143 if opts != nil {
144 c.errHandle = opts.Error
145 clog = opts.Logger
146 } else {
147 clog = slog.Default()
148 }
149 c.log = mlog.New("imapclient", clog)
150
151 c.tr = moxio.NewTraceReader(c.log, "CR: ", &c)
152 c.br = bufio.NewReader(c.tr)
153
154 // Writes are buffered and write to Conn, which may panic.
155 c.xtw = moxio.NewTraceWriter(c.log, "CW: ", &c)
156 c.xbw = bufio.NewWriter(c.xtw)
157
158 defer c.recover(&rerr, nil)
159 tag := c.xnonspace()
160 if tag != "*" {
161 c.xerrorf("expected untagged *, got %q", tag)
162 }
163 c.xspace()
164 ut := c.xuntagged()
165 switch x := ut.(type) {
166 case UntaggedResult:
167 if x.Status != OK {
168 c.xerrorf("greeting, got status %q, expected OK", x.Status)
169 }
170 if x.Code != nil {
171 if caps, ok := x.Code.(CodeCapability); ok {
172 c.CapAvailable = caps
173 }
174 }
175 return &c, nil
176 case UntaggedPreauth:
177 c.Preauth = true
178 return &c, nil
179 case UntaggedBye:
180 c.xerrorf("greeting: server sent bye")
181 default:
182 c.xerrorf("unexpected untagged %v", ut)
183 }
184 panic("not reached")
185}
186
187func (c *Conn) recover(rerr *error, resp *Response) {
188 if *rerr != nil {
189 if r, ok := (*rerr).(Response); ok && resp != nil {
190 *resp = r
191 }
192 c.errHandle(*rerr)
193 return
194 }
195
196 x := recover()
197 if x == nil {
198 return
199 }
200 var err error
201 switch e := x.(type) {
202 case Error:
203 err = e
204 case Response:
205 err = e
206 if resp != nil {
207 *resp = e
208 }
209 default:
210 panic(x)
211 }
212 if c.errHandle != nil {
213 c.errHandle(err)
214 }
215 *rerr = err
216}
217
218func (p *Proto) recover(rerr *error) {
219 if *rerr != nil {
220 return
221 }
222
223 x := recover()
224 if x == nil {
225 return
226 }
227 switch e := x.(type) {
228 case Error:
229 *rerr = e
230 default:
231 panic(x)
232 }
233}
234
235func (p *Proto) xerrorf(format string, args ...any) {
236 panic(Error{fmt.Errorf(format, args...)})
237}
238
239func (p *Proto) xcheckf(err error, format string, args ...any) {
240 if err != nil {
241 p.xerrorf("%s: %w", fmt.Sprintf(format, args...), err)
242 }
243}
244
245func (p *Proto) xcheck(err error) {
246 if err != nil {
247 panic(err)
248 }
249}
250
251// xresponse sets resp if err is a Response and resp is not nil.
252func (p *Proto) xresponse(err error, resp *Response) {
253 if err == nil {
254 return
255 }
256 if r, ok := err.(Response); ok && resp != nil {
257 *resp = r
258 }
259 panic(err)
260}
261
262// Write writes directly to underlying connection (TCP, TLS). For internal use
263// only, to implement io.Writer. Write errors do take the connection's panic mode
264// into account, i.e. Write can panic.
265func (p *Proto) Write(buf []byte) (n int, rerr error) {
266 defer p.recover(&rerr)
267
268 n, rerr = p.conn.Write(buf)
269 if rerr != nil {
270 p.connBroken = true
271 }
272 p.xcheckf(rerr, "write")
273 return n, nil
274}
275
276// Read reads directly from the underlying connection (TCP, TLS). For internal use
277// only, to implement io.Reader.
278func (p *Proto) Read(buf []byte) (n int, err error) {
279 return p.conn.Read(buf)
280}
281
282func (p *Proto) xflush() {
283 // Not writing any more when connection is broken.
284 if p.connBroken {
285 return
286 }
287
288 err := p.xbw.Flush()
289 p.xcheckf(err, "flush")
290
291 // If compression is active, we need to flush the deflate stream.
292 if p.compress {
293 err := p.xflateWriter.Flush()
294 p.xcheckf(err, "flush deflate")
295 err = p.xflateBW.Flush()
296 p.xcheckf(err, "flush deflate buffer")
297 }
298}
299
300func (p *Proto) xtraceread(level slog.Level) func() {
301 if p.tr == nil {
302 // For ParseUntagged and other parse functions.
303 return func() {}
304 }
305 p.tr.SetTrace(level)
306 return func() {
307 p.tr.SetTrace(mlog.LevelTrace)
308 }
309}
310
311func (p *Proto) xtracewrite(level slog.Level) func() {
312 if p.xtw == nil {
313 // For ParseUntagged and other parse functions.
314 return func() {}
315 }
316
317 p.xflush()
318 p.xtw.SetTrace(level)
319 return func() {
320 p.xflush()
321 p.xtw.SetTrace(mlog.LevelTrace)
322 }
323}
324
325// Close closes the connection, flushing and closing any compression and TLS layer.
326//
327// You may want to call Logout first. Closing a connection with a mailbox with
328// deleted messages not yet expunged will not expunge those messages.
329//
330// Closing a TLS connection that is logged out, or closing a TLS connection with
331// compression enabled (i.e. two layered streams), may cause spurious errors
332// because the server may immediate close the underlying connection when it sees
333// the connection is being closed.
334func (c *Conn) Close() (rerr error) {
335 defer c.recover(&rerr, nil)
336
337 if c.conn == nil {
338 return nil
339 }
340 if !c.connBroken && c.xflateWriter != nil {
341 err := c.xflateWriter.Close()
342 c.xcheckf(err, "close deflate writer")
343 err = c.xflateBW.Flush()
344 c.xcheckf(err, "flush deflate buffer")
345 c.xflateWriter = nil
346 c.xflateBW = nil
347 }
348 err := c.conn.Close()
349 c.xcheckf(err, "close connection")
350 c.conn = nil
351 return
352}
353
354// TLSConnectionState returns the TLS connection state if the connection uses TLS,
355// either because the conn passed to [New] was a TLS connection, or because
356// [Conn.StartTLS] was called.
357func (c *Conn) TLSConnectionState() *tls.ConnectionState {
358 if conn, ok := c.conn.(*tls.Conn); ok {
359 cs := conn.ConnectionState()
360 return &cs
361 }
362 return nil
363}
364
365// WriteCommandf writes a free-form IMAP command to the server. An ending \r\n is
366// written too.
367//
368// If tag is empty, a next unique tag is assigned.
369func (p *Proto) WriteCommandf(tag string, format string, args ...any) (rerr error) {
370 defer p.recover(&rerr)
371
372 if tag == "" {
373 p.nextTag()
374 } else {
375 p.lastTag = tag
376 }
377
378 fmt.Fprintf(p.xbw, "%s %s\r\n", p.lastTag, fmt.Sprintf(format, args...))
379 p.xflush()
380 return
381}
382
383func (p *Proto) nextTag() string {
384 p.tagGen++
385 p.lastTag = fmt.Sprintf("x%03d", p.tagGen)
386 return p.lastTag
387}
388
389// LastTag returns the tag last used for a command. For checking against a command
390// completion result.
391func (p *Proto) LastTag() string {
392 return p.lastTag
393}
394
395// LastTagSet sets a new last tag, as used for checking against a command completion result.
396func (p *Proto) LastTagSet(tag string) {
397 p.lastTag = tag
398}
399
400// ReadResponse reads from the IMAP server until a tagged response line is found.
401// The tag must be the same as the tag for the last written command.
402//
403// If an error is returned, resp can still be non-empty, and a caller may wish to
404// process resp.Untagged.
405//
406// Caller should check resp.Status for the result of the command too.
407//
408// Common types for the return error:
409// - Error, for protocol errors
410// - Various I/O errors from the underlying connection, including os.ErrDeadlineExceeded
411func (p *Proto) ReadResponse() (resp Response, rerr error) {
412 defer p.recover(&rerr)
413
414 for {
415 tag := p.xnonspace()
416 p.xspace()
417 if tag == "*" {
418 resp.Untagged = append(resp.Untagged, p.xuntagged())
419 continue
420 }
421
422 if tag != p.lastTag {
423 p.xerrorf("got tag %q, expected %q", tag, p.lastTag)
424 }
425
426 status := p.xstatus()
427 p.xspace()
428 resp.Result = p.xresult(status)
429 p.xcrlf()
430 return
431 }
432}
433
434// ParseCode parses a response code. The string must not have enclosing brackets.
435//
436// Example:
437//
438// "APPENDUID 123 10"
439func ParseCode(s string) (code Code, rerr error) {
440 p := Proto{br: bufio.NewReader(strings.NewReader(s + "]"))}
441 defer p.recover(&rerr)
442 code = p.xrespCode()
443 p.xtake("]")
444 buf, err := io.ReadAll(p.br)
445 p.xcheckf(err, "read")
446 if len(buf) != 0 {
447 p.xerrorf("leftover data %q", buf)
448 }
449 return code, nil
450}
451
452// ParseResult parses a line, including required crlf, as a command result line.
453//
454// Example:
455//
456// "tag1 OK [APPENDUID 123 10] message added\r\n"
457func ParseResult(s string) (tag string, result Result, rerr error) {
458 p := Proto{br: bufio.NewReader(strings.NewReader(s))}
459 defer p.recover(&rerr)
460 tag = p.xnonspace()
461 p.xspace()
462 status := p.xstatus()
463 p.xspace()
464 result = p.xresult(status)
465 p.xcrlf()
466 return
467}
468
469// ReadUntagged reads a single untagged response line.
470func (p *Proto) ReadUntagged() (untagged Untagged, rerr error) {
471 defer p.recover(&rerr)
472 return p.readUntagged()
473}
474
475// ParseUntagged parses a line, including required crlf, as untagged response.
476//
477// Example:
478//
479// "* BYE shutting down connection\r\n"
480func ParseUntagged(s string) (untagged Untagged, rerr error) {
481 p := Proto{br: bufio.NewReader(strings.NewReader(s))}
482 defer p.recover(&rerr)
483 untagged, rerr = p.readUntagged()
484 return
485}
486
487func (p *Proto) readUntagged() (untagged Untagged, rerr error) {
488 defer p.recover(&rerr)
489 tag := p.xnonspace()
490 if tag != "*" {
491 p.xerrorf("got tag %q, expected untagged", tag)
492 }
493 p.xspace()
494 ut := p.xuntagged()
495 return ut, nil
496}
497
498// Readline reads a line, including CRLF.
499// Used with IDLE and synchronous literals.
500func (p *Proto) Readline() (line string, rerr error) {
501 defer p.recover(&rerr)
502
503 line, err := p.br.ReadString('\n')
504 p.xcheckf(err, "read line")
505 return line, nil
506}
507
508func (c *Conn) readContinuation() (line string, rerr error) {
509 defer c.recover(&rerr, nil)
510 line, rerr = c.ReadContinuation()
511 if rerr != nil {
512 if resp, ok := rerr.(Response); ok {
513 c.processUntagged(resp.Untagged)
514 c.processResult(resp.Result)
515 }
516 }
517 return
518}
519
520// ReadContinuation reads a line. If it is a continuation, i.e. starts with "+", it
521// is returned without leading "+ " and without trailing crlf. Otherwise, an error
522// is returned, which can be a Response with Untagged that a caller may wish to
523// process. A successfully read continuation can return an empty line.
524func (p *Proto) ReadContinuation() (line string, rerr error) {
525 defer p.recover(&rerr)
526
527 if !p.peek('+') {
528 var resp Response
529 resp, rerr = p.ReadResponse()
530 if rerr == nil {
531 rerr = resp
532 }
533 return "", rerr
534 }
535 p.xtake("+ ")
536 line, err := p.Readline()
537 p.xcheckf(err, "read line")
538 line = strings.TrimSuffix(line, "\r\n")
539 return
540}
541
542// Writelinef writes the formatted format and args as a single line, adding CRLF.
543// Used with IDLE and synchronous literals.
544func (p *Proto) Writelinef(format string, args ...any) (rerr error) {
545 defer p.recover(&rerr)
546
547 s := fmt.Sprintf(format, args...)
548 fmt.Fprintf(p.xbw, "%s\r\n", s)
549 p.xflush()
550 return nil
551}
552
553// WriteSyncLiteral first writes the synchronous literal size, then reads the
554// continuation "+" and finally writes the data. If the literal is not accepted, an
555// error is returned, which may be a Response.
556func (p *Proto) WriteSyncLiteral(s string) (rerr error) {
557 defer p.recover(&rerr)
558
559 fmt.Fprintf(p.xbw, "{%d}\r\n", len(s))
560 p.xflush()
561
562 plus, err := p.br.Peek(1)
563 p.xcheckf(err, "read continuation")
564 if plus[0] == '+' {
565 _, err = p.Readline()
566 p.xcheckf(err, "read continuation line")
567
568 defer p.xtracewrite(mlog.LevelTracedata)()
569 _, err = p.xbw.Write([]byte(s))
570 p.xcheckf(err, "write literal data")
571 p.xtracewrite(mlog.LevelTrace)
572 return nil
573 }
574 var resp Response
575 resp, rerr = p.ReadResponse()
576 if rerr == nil {
577 rerr = resp
578 }
579 return
580}
581
582func (c *Conn) processUntagged(l []Untagged) {
583 for _, ut := range l {
584 switch e := ut.(type) {
585 case UntaggedCapability:
586 c.CapAvailable = []Capability(e)
587 case UntaggedEnabled:
588 c.CapEnabled = append(c.CapEnabled, e...)
589 }
590 }
591}
592
593func (c *Conn) processResult(r Result) {
594 if r.Code == nil {
595 return
596 }
597 switch e := r.Code.(type) {
598 case CodeCapability:
599 c.CapAvailable = []Capability(e)
600 }
601}
602
603// transactf writes format and args as an IMAP command, using Commandf with an
604// empty tag. I.e. format must not contain a tag. Transactf then reads a response
605// using ReadResponse and checks the result status is OK.
606func (c *Conn) transactf(format string, args ...any) (resp Response, rerr error) {
607 defer c.recover(&rerr, &resp)
608
609 err := c.WriteCommandf("", format, args...)
610 if err != nil {
611 return Response{}, err
612 }
613
614 return c.responseOK()
615}
616
617func (c *Conn) responseOK() (resp Response, rerr error) {
618 defer c.recover(&rerr, &resp)
619
620 resp, rerr = c.ReadResponse()
621 c.processUntagged(resp.Untagged)
622 c.processResult(resp.Result)
623 if rerr == nil && resp.Status != OK {
624 rerr = resp
625 }
626 return
627}
628