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 6package textproto 7 8// Multipart is defined in RFC 2046. 9 10import ( 11 "bufio" 12 "bytes" 13 "crypto/rand" 14 "errors" 15 "fmt" 16 "io" 17 "io/ioutil" 18) 19 20var 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. 25const peekBufferSize = 4096 26 27// A Part represents a single part in a multipart body. 28type 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. 48func 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) 64type stickyErrorReader struct { 65 r io.Reader 66 err error 67} 68 69func (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 77func 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 86func (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. 96func (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. 102type partReader struct { 103 p *Part 104} 105 106func (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. 151func 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. 206func 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 220func (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. 228type 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. 242func (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)?$` 305func (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 314func (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// LWSP-char = SPACE / HTAB 340func skipLWSPChar(b []byte) []byte { 341 for len(b) > 0 && (b[0] == ' ' || b[0] == '\t') { 342 b = b[1:] 343 } 344 return b 345} 346 347// A MultipartWriter generates multipart messages. 348type MultipartWriter struct { 349 w io.Writer 350 boundary string 351 lastpart *part 352} 353 354// NewMultipartWriter returns a new multipart Writer with a random boundary, 355// writing to w. 356func NewMultipartWriter(w io.Writer) *MultipartWriter { 357 return &MultipartWriter{ 358 w: w, 359 boundary: randomBoundary(), 360 } 361} 362 363// Boundary returns the Writer's boundary. 364func (w *MultipartWriter) Boundary() string { 365 return w.boundary 366} 367 368// SetBoundary overrides the Writer's default randomly-generated 369// boundary separator with an explicit value. 370// 371// SetBoundary must be called before any parts are created, may only 372// contain certain ASCII characters, and must be non-empty and 373// at most 70 bytes long. 374func (w *MultipartWriter) SetBoundary(boundary string) error { 375 if w.lastpart != nil { 376 return errors.New("mime: SetBoundary called after write") 377 } 378 // rfc2046#section-5.1.1 379 if len(boundary) < 1 || len(boundary) > 70 { 380 return errors.New("mime: invalid boundary length") 381 } 382 end := len(boundary) - 1 383 for i, b := range boundary { 384 if 'A' <= b && b <= 'Z' || 'a' <= b && b <= 'z' || '0' <= b && b <= '9' { 385 continue 386 } 387 switch b { 388 case '\'', '(', ')', '+', '_', ',', '-', '.', '/', ':', '=', '?': 389 continue 390 case ' ': 391 if i != end { 392 continue 393 } 394 } 395 return errors.New("mime: invalid boundary character") 396 } 397 w.boundary = boundary 398 return nil 399} 400 401func randomBoundary() string { 402 var buf [30]byte 403 _, err := io.ReadFull(rand.Reader, buf[:]) 404 if err != nil { 405 panic(err) 406 } 407 return fmt.Sprintf("%x", buf[:]) 408} 409 410// CreatePart creates a new multipart section with the provided 411// header. The body of the part should be written to the returned 412// Writer. After calling CreatePart, any previous part may no longer 413// be written to. 414func (w *MultipartWriter) CreatePart(header Header) (io.Writer, error) { 415 if w.lastpart != nil { 416 if err := w.lastpart.close(); err != nil { 417 return nil, err 418 } 419 } 420 var b bytes.Buffer 421 if w.lastpart != nil { 422 fmt.Fprintf(&b, "\r\n--%s\r\n", w.boundary) 423 } else { 424 fmt.Fprintf(&b, "--%s\r\n", w.boundary) 425 } 426 427 WriteHeader(&b, header) 428 429 _, err := io.Copy(w.w, &b) 430 if err != nil { 431 return nil, err 432 } 433 p := &part{ 434 mw: w, 435 } 436 w.lastpart = p 437 return p, nil 438} 439 440// Close finishes the multipart message and writes the trailing 441// boundary end line to the output. 442func (w *MultipartWriter) Close() error { 443 if w.lastpart != nil { 444 if err := w.lastpart.close(); err != nil { 445 return err 446 } 447 w.lastpart = nil 448 } 449 _, err := fmt.Fprintf(w.w, "\r\n--%s--\r\n", w.boundary) 450 return err 451} 452 453type part struct { 454 mw *MultipartWriter 455 closed bool 456 we error // last error that occurred writing 457} 458 459func (p *part) close() error { 460 p.closed = true 461 return p.we 462} 463 464func (p *part) Write(d []byte) (n int, err error) { 465 if p.closed { 466 return 0, errors.New("multipart: can't write to finished part") 467 } 468 n, err = p.mw.w.Write(d) 469 if err != nil { 470 p.we = err 471 } 472 return 473} 474