header.go

Documentation: net/http

     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  package http
     6  
     7  import (
     8  	"io"
     9  	"net/http/httptrace"
    10  	"net/textproto"
    11  	"sort"
    12  	"strings"
    13  	"sync"
    14  	"time"
    15  )
    16  
    17  // A Header represents the key-value pairs in an HTTP header.
    18  //
    19  // The keys should be in canonical form, as returned by
    20  // CanonicalHeaderKey.
    21  type Header map[string][]string
    22  
    23  // Add adds the key, value pair to the header.
    24  // It appends to any existing values associated with key.
    25  // The key is case insensitive; it is canonicalized by
    26  // CanonicalHeaderKey.
    27  func (h Header) Add(key, value string) {
    28  	textproto.MIMEHeader(h).Add(key, value)
    29  }
    30  
    31  // Set sets the header entries associated with key to the
    32  // single element value. It replaces any existing values
    33  // associated with key. The key is case insensitive; it is
    34  // canonicalized by textproto.CanonicalMIMEHeaderKey.
    35  // To use non-canonical keys, assign to the map directly.
    36  func (h Header) Set(key, value string) {
    37  	textproto.MIMEHeader(h).Set(key, value)
    38  }
    39  
    40  // Get gets the first value associated with the given key. If
    41  // there are no values associated with the key, Get returns "".
    42  // It is case insensitive; textproto.CanonicalMIMEHeaderKey is
    43  // used to canonicalize the provided key. To use non-canonical keys,
    44  // access the map directly.
    45  func (h Header) Get(key string) string {
    46  	return textproto.MIMEHeader(h).Get(key)
    47  }
    48  
    49  // Values returns all values associated with the given key.
    50  // It is case insensitive; textproto.CanonicalMIMEHeaderKey is
    51  // used to canonicalize the provided key. To use non-canonical
    52  // keys, access the map directly.
    53  // The returned slice is not a copy.
    54  func (h Header) Values(key string) []string {
    55  	return textproto.MIMEHeader(h).Values(key)
    56  }
    57  
    58  // get is like Get, but key must already be in CanonicalHeaderKey form.
    59  func (h Header) get(key string) string {
    60  	if v := h[key]; len(v) > 0 {
    61  		return v[0]
    62  	}
    63  	return ""
    64  }
    65  
    66  // has reports whether h has the provided key defined, even if it's
    67  // set to 0-length slice.
    68  func (h Header) has(key string) bool {
    69  	_, ok := h[key]
    70  	return ok
    71  }
    72  
    73  // Del deletes the values associated with key.
    74  // The key is case insensitive; it is canonicalized by
    75  // CanonicalHeaderKey.
    76  func (h Header) Del(key string) {
    77  	textproto.MIMEHeader(h).Del(key)
    78  }
    79  
    80  // Write writes a header in wire format.
    81  func (h Header) Write(w io.Writer) error {
    82  	return h.write(w, nil)
    83  }
    84  
    85  func (h Header) write(w io.Writer, trace *httptrace.ClientTrace) error {
    86  	return h.writeSubset(w, nil, trace)
    87  }
    88  
    89  // Clone returns a copy of h or nil if h is nil.
    90  func (h Header) Clone() Header {
    91  	if h == nil {
    92  		return nil
    93  	}
    94  
    95  	// Find total number of values.
    96  	nv := 0
    97  	for _, vv := range h {
    98  		nv += len(vv)
    99  	}
   100  	sv := make([]string, nv) // shared backing array for headers' values
   101  	h2 := make(Header, len(h))
   102  	for k, vv := range h {
   103  		n := copy(sv, vv)
   104  		h2[k] = sv[:n:n]
   105  		sv = sv[n:]
   106  	}
   107  	return h2
   108  }
   109  
   110  var timeFormats = []string{
   111  	TimeFormat,
   112  	time.RFC850,
   113  	time.ANSIC,
   114  }
   115  
   116  // ParseTime parses a time header (such as the Date: header),
   117  // trying each of the three formats allowed by HTTP/1.1:
   118  // TimeFormat, time.RFC850, and time.ANSIC.
   119  func ParseTime(text string) (t time.Time, err error) {
   120  	for _, layout := range timeFormats {
   121  		t, err = time.Parse(layout, text)
   122  		if err == nil {
   123  			return
   124  		}
   125  	}
   126  	return
   127  }
   128  
   129  var headerNewlineToSpace = strings.NewReplacer("\n", " ", "\r", " ")
   130  
   131  // stringWriter implements WriteString on a Writer.
   132  type stringWriter struct {
   133  	w io.Writer
   134  }
   135  
   136  func (w stringWriter) WriteString(s string) (n int, err error) {
   137  	return w.w.Write([]byte(s))
   138  }
   139  
   140  type keyValues struct {
   141  	key    string
   142  	values []string
   143  }
   144  
   145  // A headerSorter implements sort.Interface by sorting a []keyValues
   146  // by key. It's used as a pointer, so it can fit in a sort.Interface
   147  // interface value without allocation.
   148  type headerSorter struct {
   149  	kvs []keyValues
   150  }
   151  
   152  func (s *headerSorter) Len() int           { return len(s.kvs) }
   153  func (s *headerSorter) Swap(i, j int)      { s.kvs[i], s.kvs[j] = s.kvs[j], s.kvs[i] }
   154  func (s *headerSorter) Less(i, j int) bool { return s.kvs[i].key < s.kvs[j].key }
   155  
   156  var headerSorterPool = sync.Pool{
   157  	New: func() interface{} { return new(headerSorter) },
   158  }
   159  
   160  // sortedKeyValues returns h's keys sorted in the returned kvs
   161  // slice. The headerSorter used to sort is also returned, for possible
   162  // return to headerSorterCache.
   163  func (h Header) sortedKeyValues(exclude map[string]bool) (kvs []keyValues, hs *headerSorter) {
   164  	hs = headerSorterPool.Get().(*headerSorter)
   165  	if cap(hs.kvs) < len(h) {
   166  		hs.kvs = make([]keyValues, 0, len(h))
   167  	}
   168  	kvs = hs.kvs[:0]
   169  	for k, vv := range h {
   170  		if !exclude[k] {
   171  			kvs = append(kvs, keyValues{k, vv})
   172  		}
   173  	}
   174  	hs.kvs = kvs
   175  	sort.Sort(hs)
   176  	return kvs, hs
   177  }
   178  
   179  // WriteSubset writes a header in wire format.
   180  // If exclude is not nil, keys where exclude[key] == true are not written.
   181  // Keys are not canonicalized before checking the exclude map.
   182  func (h Header) WriteSubset(w io.Writer, exclude map[string]bool) error {
   183  	return h.writeSubset(w, exclude, nil)
   184  }
   185  
   186  func (h Header) writeSubset(w io.Writer, exclude map[string]bool, trace *httptrace.ClientTrace) error {
   187  	ws, ok := w.(io.StringWriter)
   188  	if !ok {
   189  		ws = stringWriter{w}
   190  	}
   191  	kvs, sorter := h.sortedKeyValues(exclude)
   192  	var formattedVals []string
   193  	for _, kv := range kvs {
   194  		for _, v := range kv.values {
   195  			v = headerNewlineToSpace.Replace(v)
   196  			v = textproto.TrimString(v)
   197  			for _, s := range []string{kv.key, ": ", v, "\r\n"} {
   198  				if _, err := ws.WriteString(s); err != nil {
   199  					headerSorterPool.Put(sorter)
   200  					return err
   201  				}
   202  			}
   203  			if trace != nil && trace.WroteHeaderField != nil {
   204  				formattedVals = append(formattedVals, v)
   205  			}
   206  		}
   207  		if trace != nil && trace.WroteHeaderField != nil {
   208  			trace.WroteHeaderField(kv.key, formattedVals)
   209  			formattedVals = nil
   210  		}
   211  	}
   212  	headerSorterPool.Put(sorter)
   213  	return nil
   214  }
   215  
   216  // CanonicalHeaderKey returns the canonical format of the
   217  // header key s. The canonicalization converts the first
   218  // letter and any letter following a hyphen to upper case;
   219  // the rest are converted to lowercase. For example, the
   220  // canonical key for "accept-encoding" is "Accept-Encoding".
   221  // If s contains a space or invalid header field bytes, it is
   222  // returned without modifications.
   223  func CanonicalHeaderKey(s string) string { return textproto.CanonicalMIMEHeaderKey(s) }
   224  
   225  // hasToken reports whether token appears with v, ASCII
   226  // case-insensitive, with space or comma boundaries.
   227  // token must be all lowercase.
   228  // v may contain mixed cased.
   229  func hasToken(v, token string) bool {
   230  	if len(token) > len(v) || token == "" {
   231  		return false
   232  	}
   233  	if v == token {
   234  		return true
   235  	}
   236  	for sp := 0; sp <= len(v)-len(token); sp++ {
   237  		// Check that first character is good.
   238  		// The token is ASCII, so checking only a single byte
   239  		// is sufficient. We skip this potential starting
   240  		// position if both the first byte and its potential
   241  		// ASCII uppercase equivalent (b|0x20) don't match.
   242  		// False positives ('^' => '~') are caught by EqualFold.
   243  		if b := v[sp]; b != token[0] && b|0x20 != token[0] {
   244  			continue
   245  		}
   246  		// Check that start pos is on a valid token boundary.
   247  		if sp > 0 && !isTokenBoundary(v[sp-1]) {
   248  			continue
   249  		}
   250  		// Check that end pos is on a valid token boundary.
   251  		if endPos := sp + len(token); endPos != len(v) && !isTokenBoundary(v[endPos]) {
   252  			continue
   253  		}
   254  		if strings.EqualFold(v[sp:sp+len(token)], token) {
   255  			return true
   256  		}
   257  	}
   258  	return false
   259  }
   260  
   261  func isTokenBoundary(b byte) bool {
   262  	return b == ' ' || b == ',' || b == '\t'
   263  }
   264
View as plain text