1 // Copyright 2010 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 //
5 6 package textproto
7 8 // Multipart is defined in RFC 2046.
9 10 import (
11 "bufio"
12 "bytes"
13 "crypto/rand"
14 "errors"
15 "fmt"
16 "io"
17 "io/ioutil"
18 )
19 20 var emptyParams = make(map[string]string)
21 22 // This constant needs to be at least 76 for this package to work correctly.
23 // This is because \r\n--separator_of_len_70- would fill the buffer and it
24 // wouldn't be safe to consume a single byte from it.
25 const peekBufferSize = 4096
26 27 // A Part represents a single part in a multipart body.
28 type Part struct {
29 Header Header
30 31 mr *MultipartReader
32 33 // r is either a reader directly reading from mr
34 r io.Reader
35 36 n int // known data bytes waiting in mr.bufReader
37 total int64 // total data bytes read already
38 err error // error to return when n == 0
39 readErr error // read error observed from mr.bufReader
40 }
41 42 // NewMultipartReader creates a new multipart reader reading from r using the
43 // given MIME boundary.
44 //
45 // The boundary is usually obtained from the "boundary" parameter of
46 // the message's "Content-Type" header. Use mime.ParseMediaType to
47 // parse such headers.
48 func NewMultipartReader(r io.Reader, boundary string) *MultipartReader {
49 b := []byte("\r\n--" + boundary + "--")
50 return &MultipartReader{
51 bufReader: bufio.NewReaderSize(&stickyErrorReader{r: r}, peekBufferSize),
52 nl: b[:2],
53 nlDashBoundary: b[:len(b)-2],
54 dashBoundaryDash: b[2:],
55 dashBoundary: b[2 : len(b)-2],
56 }
57 }
58 59 // stickyErrorReader is an io.Reader which never calls Read on its
60 // underlying Reader once an error has been seen. (the io.Reader
61 // interface's contract promises nothing about the return values of
62 // Read calls after an error, yet this package does do multiple Reads
63 // after error)
64 type stickyErrorReader struct {
65 r io.Reader
66 err error
67 }
68 69 func (r *stickyErrorReader) Read(p []byte) (n int, _ error) {
70 if r.err != nil {
71 return 0, r.err
72 }
73 n, r.err = r.r.Read(p)
74 return n, r.err
75 }
76 77 func newPart(mr *MultipartReader) (*Part, error) {
78 bp := &Part{mr: mr}
79 if err := bp.populateHeaders(); err != nil {
80 return nil, err
81 }
82 bp.r = partReader{bp}
83 return bp, nil
84 }
85 86 func (bp *Part) populateHeaders() error {
87 header, err := ReadHeader(bp.mr.bufReader)
88 if err == nil {
89 bp.Header = header
90 }
91 return err
92 }
93 94 // Read reads the body of a part, after its headers and before the
95 // next part (if any) begins.
96 func (p *Part) Read(d []byte) (n int, err error) {
97 return p.r.Read(d)
98 }
99 100 // partReader implements io.Reader by reading raw bytes directly from the
101 // wrapped *Part, without doing any Transfer-Encoding decoding.
102 type partReader struct {
103 p *Part
104 }
105 106 func (pr partReader) Read(d []byte) (int, error) {
107 p := pr.p
108 br := p.mr.bufReader
109 110 // Read into buffer until we identify some data to return,
111 // or we find a reason to stop (boundary or read error).
112 for p.n == 0 && p.err == nil {
113 peek, _ := br.Peek(br.Buffered())
114 p.n, p.err = scanUntilBoundary(peek, p.mr.dashBoundary, p.mr.nlDashBoundary, p.total, p.readErr)
115 if p.n == 0 && p.err == nil {
116 // Force buffered I/O to read more into buffer.
117 _, p.readErr = br.Peek(len(peek) + 1)
118 if p.readErr == io.EOF {
119 p.readErr = io.ErrUnexpectedEOF
120 }
121 }
122 }
123 124 // Read out from "data to return" part of buffer.
125 if p.n == 0 {
126 return 0, p.err
127 }
128 n := len(d)
129 if n > p.n {
130 n = p.n
131 }
132 n, _ = br.Read(d[:n])
133 p.total += int64(n)
134 p.n -= n
135 if p.n == 0 {
136 return n, p.err
137 }
138 return n, nil
139 }
140 141 // scanUntilBoundary scans buf to identify how much of it can be safely
142 // returned as part of the Part body.
143 // dashBoundary is "--boundary".
144 // nlDashBoundary is "\r\n--boundary" or "\n--boundary", depending on what mode we are in.
145 // The comments below (and the name) assume "\n--boundary", but either is accepted.
146 // total is the number of bytes read out so far. If total == 0, then a leading "--boundary" is recognized.
147 // readErr is the read error, if any, that followed reading the bytes in buf.
148 // scanUntilBoundary returns the number of data bytes from buf that can be
149 // returned as part of the Part body and also the error to return (if any)
150 // once those data bytes are done.
151 func scanUntilBoundary(buf, dashBoundary, nlDashBoundary []byte, total int64, readErr error) (int, error) {
152 if total == 0 {
153 // At beginning of body, allow dashBoundary.
154 if bytes.HasPrefix(buf, dashBoundary) {
155 switch matchAfterPrefix(buf, dashBoundary, readErr) {
156 case -1:
157 return len(dashBoundary), nil
158 case 0:
159 return 0, nil
160 case +1:
161 return 0, io.EOF
162 }
163 }
164 if bytes.HasPrefix(dashBoundary, buf) {
165 return 0, readErr
166 }
167 }
168 169 // Search for "\n--boundary".
170 if i := bytes.Index(buf, nlDashBoundary); i >= 0 {
171 switch matchAfterPrefix(buf[i:], nlDashBoundary, readErr) {
172 case -1:
173 return i + len(nlDashBoundary), nil
174 case 0:
175 return i, nil
176 case +1:
177 return i, io.EOF
178 }
179 }
180 if bytes.HasPrefix(nlDashBoundary, buf) {
181 return 0, readErr
182 }
183 184 // Otherwise, anything up to the final \n is not part of the boundary
185 // and so must be part of the body.
186 // Also if the section from the final \n onward is not a prefix of the boundary,
187 // it too must be part of the body.
188 i := bytes.LastIndexByte(buf, nlDashBoundary[0])
189 if i >= 0 && bytes.HasPrefix(nlDashBoundary, buf[i:]) {
190 return i, nil
191 }
192 return len(buf), readErr
193 }
194 195 // matchAfterPrefix checks whether buf should be considered to match the boundary.
196 // The prefix is "--boundary" or "\r\n--boundary" or "\n--boundary",
197 // and the caller has verified already that bytes.HasPrefix(buf, prefix) is true.
198 //
199 // matchAfterPrefix returns +1 if the buffer does match the boundary,
200 // meaning the prefix is followed by a dash, space, tab, cr, nl, or end of input.
201 // It returns -1 if the buffer definitely does NOT match the boundary,
202 // meaning the prefix is followed by some other character.
203 // For example, "--foobar" does not match "--foo".
204 // It returns 0 more input needs to be read to make the decision,
205 // meaning that len(buf) == len(prefix) and readErr == nil.
206 func matchAfterPrefix(buf, prefix []byte, readErr error) int {
207 if len(buf) == len(prefix) {
208 if readErr != nil {
209 return +1
210 }
211 return 0
212 }
213 c := buf[len(prefix)]
214 if c == ' ' || c == '\t' || c == '\r' || c == '\n' || c == '-' {
215 return +1
216 }
217 return -1
218 }
219 220 func (p *Part) Close() error {
221 io.Copy(ioutil.Discard, p)
222 return nil
223 }
224 225 // MultipartReader is an iterator over parts in a MIME multipart body.
226 // MultipartReader's underlying parser consumes its input as needed. Seeking
227 // isn't supported.
228 type MultipartReader struct {
229 bufReader *bufio.Reader
230 231 currentPart *Part
232 partsRead int
233 234 nl []byte // "\r\n" or "\n" (set after seeing first boundary line)
235 nlDashBoundary []byte // nl + "--boundary"
236 dashBoundaryDash []byte // "--boundary--"
237 dashBoundary []byte // "--boundary"
238 }
239 240 // NextPart returns the next part in the multipart or an error.
241 // When there are no more parts, the error io.EOF is returned.
242 func (r *MultipartReader) NextPart() (*Part, error) {
243 if r.currentPart != nil {
244 r.currentPart.Close()
245 }
246 if string(r.dashBoundary) == "--" {
247 return nil, fmt.Errorf("multipart: boundary is empty")
248 }
249 expectNewPart := false
250 for {
251 line, err := r.bufReader.ReadSlice('\n')
252 253 if err == io.EOF && r.isFinalBoundary(line) {
254 // If the buffer ends in "--boundary--" without the
255 // trailing "\r\n", ReadSlice will return an error
256 // (since it's missing the '\n'), but this is a valid
257 // multipart EOF so we need to return io.EOF instead of
258 // a fmt-wrapped one.
259 return nil, io.EOF
260 }
261 if err != nil {
262 return nil, fmt.Errorf("multipart: NextPart: %v", err)
263 }
264 265 if r.isBoundaryDelimiterLine(line) {
266 r.partsRead++
267 bp, err := newPart(r)
268 if err != nil {
269 return nil, err
270 }
271 r.currentPart = bp
272 return bp, nil
273 }
274 275 if r.isFinalBoundary(line) {
276 // Expected EOF
277 return nil, io.EOF
278 }
279 280 if expectNewPart {
281 return nil, fmt.Errorf("multipart: expecting a new Part; got line %q", string(line))
282 }
283 284 if r.partsRead == 0 {
285 // skip line
286 continue
287 }
288 289 // Consume the "\n" or "\r\n" separator between the
290 // body of the previous part and the boundary line we
291 // now expect will follow. (either a new part or the
292 // end boundary)
293 if bytes.Equal(line, r.nl) {
294 expectNewPart = true
295 continue
296 }
297 298 return nil, fmt.Errorf("multipart: unexpected line in Next(): %q", line)
299 }
300 }
301 302 // isFinalBoundary reports whether line is the final boundary line
303 // indicating that all parts are over.
304 // It matches `^--boundary--[ \t]*(\r\n)?$`
305 func (mr *MultipartReader) isFinalBoundary(line []byte) bool {
306 if !bytes.HasPrefix(line, mr.dashBoundaryDash) {
307 return false
308 }
309 rest := line[len(mr.dashBoundaryDash):]
310 rest = skipLWSPChar(rest)
311 return len(rest) == 0 || bytes.Equal(rest, mr.nl)
312 }
313 314 func (mr *MultipartReader) isBoundaryDelimiterLine(line []byte) (ret bool) {
315 // https://tools.ietf.org/html/rfc2046#section-5.1
316 // The boundary delimiter line is then defined as a line
317 // consisting entirely of two hyphen characters ("-",
318 // decimal value 45) followed by the boundary parameter
319 // value from the Content-Type header field, optional linear
320 // whitespace, and a terminating CRLF.
321 if !bytes.HasPrefix(line, mr.dashBoundary) {
322 return false
323 }
324 rest := line[len(mr.dashBoundary):]
325 rest = skipLWSPChar(rest)
326 327 // On the first part, see our lines are ending in \n instead of \r\n
328 // and switch into that mode if so. This is a violation of the spec,
329 // but occurs in practice.
330 if mr.partsRead == 0 && len(rest) == 1 && rest[0] == '\n' {
331 mr.nl = mr.nl[1:]
332 mr.nlDashBoundary = mr.nlDashBoundary[1:]
333 }
334 return bytes.Equal(rest, mr.nl)
335 }
336 337 // skipLWSPChar returns b with leading spaces and tabs removed.
338 // RFC 822 defines:
339 //
340 // LWSP-char = SPACE / HTAB
341 func skipLWSPChar(b []byte) []byte {
342 for len(b) > 0 && (b[0] == ' ' || b[0] == '\t') {
343 b = b[1:]
344 }
345 return b
346 }
347 348 // A MultipartWriter generates multipart messages.
349 type MultipartWriter struct {
350 w io.Writer
351 boundary string
352 lastpart *part
353 }
354 355 // NewMultipartWriter returns a new multipart Writer with a random boundary,
356 // writing to w.
357 func NewMultipartWriter(w io.Writer) *MultipartWriter {
358 return &MultipartWriter{
359 w: w,
360 boundary: randomBoundary(),
361 }
362 }
363 364 // Boundary returns the Writer's boundary.
365 func (w *MultipartWriter) Boundary() string {
366 return w.boundary
367 }
368 369 // SetBoundary overrides the Writer's default randomly-generated
370 // boundary separator with an explicit value.
371 //
372 // SetBoundary must be called before any parts are created, may only
373 // contain certain ASCII characters, and must be non-empty and
374 // at most 70 bytes long.
375 func (w *MultipartWriter) SetBoundary(boundary string) error {
376 if w.lastpart != nil {
377 return errors.New("mime: SetBoundary called after write")
378 }
379 // rfc2046#section-5.1.1
380 if len(boundary) < 1 || len(boundary) > 70 {
381 return errors.New("mime: invalid boundary length")
382 }
383 end := len(boundary) - 1
384 for i, b := range boundary {
385 if 'A' <= b && b <= 'Z' || 'a' <= b && b <= 'z' || '0' <= b && b <= '9' {
386 continue
387 }
388 switch b {
389 case '\'', '(', ')', '+', '_', ',', '-', '.', '/', ':', '=', '?':
390 continue
391 case ' ':
392 if i != end {
393 continue
394 }
395 }
396 return errors.New("mime: invalid boundary character")
397 }
398 w.boundary = boundary
399 return nil
400 }
401 402 func randomBoundary() string {
403 var buf [30]byte
404 _, err := io.ReadFull(rand.Reader, buf[:])
405 if err != nil {
406 panic(err)
407 }
408 return fmt.Sprintf("%x", buf[:])
409 }
410 411 // CreatePart creates a new multipart section with the provided
412 // header. The body of the part should be written to the returned
413 // Writer. After calling CreatePart, any previous part may no longer
414 // be written to.
415 func (w *MultipartWriter) CreatePart(header Header) (io.Writer, error) {
416 if w.lastpart != nil {
417 if err := w.lastpart.close(); err != nil {
418 return nil, err
419 }
420 }
421 var b bytes.Buffer
422 if w.lastpart != nil {
423 fmt.Fprintf(&b, "\r\n--%s\r\n", w.boundary)
424 } else {
425 fmt.Fprintf(&b, "--%s\r\n", w.boundary)
426 }
427 428 WriteHeader(&b, header)
429 430 _, err := io.Copy(w.w, &b)
431 if err != nil {
432 return nil, err
433 }
434 p := &part{
435 mw: w,
436 }
437 w.lastpart = p
438 return p, nil
439 }
440 441 // Close finishes the multipart message and writes the trailing
442 // boundary end line to the output.
443 func (w *MultipartWriter) Close() error {
444 if w.lastpart != nil {
445 if err := w.lastpart.close(); err != nil {
446 return err
447 }
448 w.lastpart = nil
449 }
450 _, err := fmt.Fprintf(w.w, "\r\n--%s--\r\n", w.boundary)
451 return err
452 }
453 454 type part struct {
455 mw *MultipartWriter
456 closed bool
457 we error // last error that occurred writing
458 }
459 460 func (p *part) close() error {
461 p.closed = true
462 return p.we
463 }
464 465 func (p *part) Write(d []byte) (n int, err error) {
466 if p.closed {
467 return 0, errors.New("multipart: can't write to finished part")
468 }
469 n, err = p.mw.w.Write(d)
470 if err != nil {
471 p.we = err
472 }
473 return
474 }
475