multipart.go

Documentation: mime/multipart

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