1/*

2Package imapclient provides an IMAP4 client, primarily for testing the IMAP4 server.

3

4Commands can be sent to the server free-form, but responses are parsed strictly.

5Behaviour that may not be required by the IMAP4 specification may be expected by

6this client.

7*/

8package imapclient

9

10/*

11- Try to keep the parsing method names and the types similar to the ABNF names in the RFCs.

12

13- todo: have mode for imap4rev1 vs imap4rev2, refusing what is not allowed. we are accepting too much now.

14- todo: stricter parsing. xnonspace() and xword() should be replaced by proper parsers.

15*/

16

17import (

18 "bufio"

19 "crypto/tls"

20 "fmt"

21 "net"

22 "reflect"

23 "strings"

24)

25

26// Conn is an IMAP connection to a server.

27type Conn struct {

28 conn net.Conn

29 r *bufio.Reader

30 panic bool

31 tagGen int

32 record bool // If true, bytes read are added to recordBuf. recorded() resets.

33 recordBuf []byte

34

35 LastTag string

36 CapAvailable map[Capability]struct{} // Capabilities available at server, from CAPABILITY command or response code.

37 CapEnabled map[Capability]struct{} // Capabilities enabled through ENABLE command.

38}

39

40// Error is a parse or other protocol error.

41type Error struct{ err error }

42

43func (e Error) Error() string {

44 return e.err.Error()

45}

46

47func (e Error) Unwrap() error {

48 return e.err

49}

50

51// New creates a new client on conn.

52//

53// If xpanic is true, functions that would return an error instead panic. For parse

54// errors, the resulting stack traces show typically show what was being parsed.

55//

56// The initial untagged greeting response is read and must be "OK".

57func New(conn net.Conn, xpanic bool) (client *Conn, rerr error) {

58 c := Conn{

59 conn: conn,

60 r: bufio.NewReader(conn),

61 panic: xpanic,

62 CapAvailable: map[Capability]struct{}{},

63 CapEnabled: map[Capability]struct{}{},

64 }

65

66 defer c.recover(&rerr)

67 tag := c.xnonspace()

68 if tag != "*" {

69 c.xerrorf("expected untagged *, got %q", tag)

70 }

71 c.xspace()

72 ut := c.xuntagged()

73 switch x := ut.(type) {

74 case UntaggedResult:

75 if x.Status != OK {

76 c.xerrorf("greeting, got status %q, expected OK", x.Status)

77 }

78 return &c, nil

79 case UntaggedPreauth:

80 c.xerrorf("greeting: unexpected preauth")

81 case UntaggedBye:

82 c.xerrorf("greeting: server sent bye")

83 default:

84 c.xerrorf("unexpected untagged %v", ut)

85 }

86 panic("not reached")

87}

88

89func (c *Conn) recover(rerr *error) {

90 if c.panic {

91 return

92 }

93

94 x := recover()

95 if x == nil {

96 return

97 }

98 err, ok := x.(Error)

99 if !ok {

100 panic(x)

101 }

102 *rerr = err

103}

104

105func (c *Conn) xerrorf(format string, args ...any) {

106 panic(Error{fmt.Errorf(format, args...)})

107}

108

109func (c *Conn) xcheckf(err error, format string, args ...any) {

110 if err != nil {

111 c.xerrorf("%s: %w", fmt.Sprintf(format, args...), err)

112 }

113}

114

115func (c *Conn) xcheck(err error) {

116 if err != nil {

117 panic(err)

118 }

119}

120

121// TLSConnectionState returns the TLS connection state if the connection uses TLS.

122func (c *Conn) TLSConnectionState() *tls.ConnectionState {

123 if conn, ok := c.conn.(*tls.Conn); ok {

124 cs := conn.ConnectionState()

125 return &cs

126 }

127 return nil

128}

129

130// Commandf writes a free-form IMAP command to the server.

131// If tag is empty, a next unique tag is assigned.

132func (c *Conn) Commandf(tag string, format string, args ...any) (rerr error) {

133 defer c.recover(&rerr)

134

135 if tag == "" {

136 tag = c.nextTag()

137 }

138 c.LastTag = tag

139

140 _, err := fmt.Fprintf(c.conn, "%s %s\r\n", tag, fmt.Sprintf(format, args...))

141 c.xcheckf(err, "write command")

142 return

143}

144

145func (c *Conn) nextTag() string {

146 c.tagGen++

147 return fmt.Sprintf("x%03d", c.tagGen)

148}

149

150// Response reads from the IMAP server until a tagged response line is found.

151// The tag must be the same as the tag for the last written command.

152// Result holds the status of the command. The caller must check if this the status is OK.

153func (c *Conn) Response() (untagged []Untagged, result Result, rerr error) {

154 defer c.recover(&rerr)

155

156 for {

157 tag := c.xnonspace()

158 c.xspace()

159 if tag == "*" {

160 untagged = append(untagged, c.xuntagged())

161 continue

162 }

163

164 if tag != c.LastTag {

165 c.xerrorf("got tag %q, expected %q", tag, c.LastTag)

166 }

167

168 status := c.xstatus()

169 c.xspace()

170 result = c.xresult(status)

171 c.xcrlf()

172 return

173 }

174}

175

176// ReadUntagged reads a single untagged response line.

177// Useful for reading lines from IDLE.

178func (c *Conn) ReadUntagged() (untagged Untagged, rerr error) {

179 defer c.recover(&rerr)

180

181 tag := c.xnonspace()

182 if tag != "*" {

183 c.xerrorf("got tag %q, expected untagged", tag)

184 }

185 c.xspace()

186 ut := c.xuntagged()

187 return ut, nil

188}

189

190// Readline reads a line, including CRLF.

191// Used with IDLE and synchronous literals.

192func (c *Conn) Readline() (line string, rerr error) {

193 defer c.recover(&rerr)

194

195 line, err := c.r.ReadString('\n')

196 c.xcheckf(err, "read line")

197 return line, nil

198}

199

200// ReadContinuation reads a line. If it is a continuation, i.e. starts with a +, it

201// is returned without leading "+ " and without trailing crlf. Otherwise, a command

202// response is returned. A successfully read continuation can return an empty line.

203// Callers should check rerr and result.Status being empty to check if a

204// continuation was read.

205func (c *Conn) ReadContinuation() (line string, untagged []Untagged, result Result, rerr error) {

206 if !c.peek('+') {

207 untagged, result, rerr = c.Response()

208 c.xcheckf(rerr, "reading non-continuation response")

209 c.xerrorf("response status %q, expected OK", result.Status)

210 }

211 c.xtake("+ ")

212 line, err := c.Readline()

213 c.xcheckf(err, "read line")

214 line = strings.TrimSuffix(line, "\r\n")

215 return

216}

217

218// Writelinef writes the formatted format and args as a single line, adding CRLF.

219// Used with IDLE and synchronous literals.

220func (c *Conn) Writelinef(format string, args ...any) (rerr error) {

221 defer c.recover(&rerr)

222

223 s := fmt.Sprintf(format, args...)

224 _, err := fmt.Fprintf(c.conn, "%s\r\n", s)

225 c.xcheckf(err, "writeline")

226 return nil

227}

228

229// Write writes directly to the connection. Write errors do take the connections

230// panic mode into account, i.e. Write can panic.

231func (c *Conn) Write(buf []byte) (n int, rerr error) {

232 defer c.recover(&rerr)

233

234 n, rerr = c.conn.Write(buf)

235 c.xcheckf(rerr, "write")

236 return n, nil

237}

238

239// WriteSyncLiteral first writes the synchronous literal size, then read the

240// continuation "+" and finally writes the data.

241func (c *Conn) WriteSyncLiteral(s string) (rerr error) {

242 defer c.recover(&rerr)

243

244 _, err := fmt.Fprintf(c.conn, "{%d}\r\n", len(s))

245 c.xcheckf(err, "write sync literal size")

246 line, err := c.Readline()

247 c.xcheckf(err, "read line")

248 if !strings.HasPrefix(line, "+") {

249 c.xerrorf("no continuation received for sync literal")

250 }

251 _, err = c.conn.Write([]byte(s))

252 c.xcheckf(err, "write literal data")

253 return nil

254}

255

256// Transactf writes format and args as an IMAP command, using Commandf with an

257// empty tag. I.e. format must not contain a tag. Transactf then reads a response

258// using ReadResponse and checks the result status is OK.

259func (c *Conn) Transactf(format string, args ...any) (untagged []Untagged, result Result, rerr error) {

260 defer c.recover(&rerr)

261

262 err := c.Commandf("", format, args...)

263 if err != nil {

264 return nil, Result{}, err

265 }

266 return c.ResponseOK()

267}

268

269func (c *Conn) ResponseOK() (untagged []Untagged, result Result, rerr error) {

270 untagged, result, rerr = c.Response()

271 if rerr != nil {

272 return nil, Result{}, rerr

273 }

274 if result.Status != OK {

275 c.xerrorf("response status %q, expected OK", result.Status)

276 }

277 return untagged, result, rerr

278}

279

280func (c *Conn) xgetUntagged(l []Untagged, dst any) {

281 if len(l) != 1 {

282 c.xerrorf("got %d untagged, expected 1: %v", len(l), l)

283 }

284 got := l[0]

285 gotv := reflect.ValueOf(got)

286 dstv := reflect.ValueOf(dst)

287 if gotv.Type() != dstv.Type().Elem() {

288 c.xerrorf("got %v, expected %v", gotv.Type(), dstv.Type().Elem())

289 }

290 dstv.Elem().Set(gotv)

291}

292

293// Close closes the connection without writing anything to the server.

294// You may want to call Logout. Closing a connection with a mailbox with deleted

295// message not yet expunged will not expunge those messages.

296func (c *Conn) Close() error {

297 var err error

298 if c.conn != nil {

299 err = c.conn.Close()

300 c.conn = nil

301 }

302 return err

303}

304