1 // Copyright 2016 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 "strconv" 10 "strings" 11 "time" 12 "unicode/utf8" 13 14 "golang.org/x/net/http/httpguts" 15 ) 16 17 // maxInt64 is the effective "infinite" value for the Server and 18 // Transport's byte-limiting readers. 19 const maxInt64 = 1<<63 - 1 20 21 // aLongTimeAgo is a non-zero time, far in the past, used for 22 // immediate cancellation of network operations. 23 var aLongTimeAgo = time.Unix(1, 0) 24 25 // TODO(bradfitz): move common stuff here. The other files have accumulated 26 // generic http stuff in random places. 27 28 // contextKey is a value for use with context.WithValue. It's used as 29 // a pointer so it fits in an interface{} without allocation. 30 type contextKey struct { 31 name string 32 } 33 34 func (k *contextKey) String() string { return "net/http context value " + k.name } 35 36 // Given a string of the form "host", "host:port", or "[ipv6::address]:port", 37 // return true if the string includes a port. 38 func hasPort(s string) bool { return strings.LastIndex(s, ":") > strings.LastIndex(s, "]") } 39 40 // removeEmptyPort strips the empty port in ":port" to "" 41 // as mandated by RFC 3986 Section 6.2.3. 42 func removeEmptyPort(host string) string { 43 if hasPort(host) { 44 return strings.TrimSuffix(host, ":") 45 } 46 return host 47 } 48 49 func isNotToken(r rune) bool { 50 return !httpguts.IsTokenRune(r) 51 } 52 53 func isASCII(s string) bool { 54 for i := 0; i < len(s); i++ { 55 if s[i] >= utf8.RuneSelf { 56 return false 57 } 58 } 59 return true 60 } 61 62 // stringContainsCTLByte reports whether s contains any ASCII control character. 63 func stringContainsCTLByte(s string) bool { 64 for i := 0; i < len(s); i++ { 65 b := s[i] 66 if b < ' ' || b == 0x7f { 67 return true 68 } 69 } 70 return false 71 } 72 73 func hexEscapeNonASCII(s string) string { 74 newLen := 0 75 for i := 0; i < len(s); i++ { 76 if s[i] >= utf8.RuneSelf { 77 newLen += 3 78 } else { 79 newLen++ 80 } 81 } 82 if newLen == len(s) { 83 return s 84 } 85 b := make([]byte, 0, newLen) 86 for i := 0; i < len(s); i++ { 87 if s[i] >= utf8.RuneSelf { 88 b = append(b, '%') 89 b = strconv.AppendInt(b, int64(s[i]), 16) 90 } else { 91 b = append(b, s[i]) 92 } 93 } 94 return string(b) 95 } 96 97 // NoBody is an io.ReadCloser with no bytes. Read always returns EOF 98 // and Close always returns nil. It can be used in an outgoing client 99 // request to explicitly signal that a request has zero bytes. 100 // An alternative, however, is to simply set Request.Body to nil. 101 var NoBody = noBody{} 102 103 type noBody struct{} 104 105 func (noBody) Read([]byte) (int, error) { return 0, io.EOF } 106 func (noBody) Close() error { return nil } 107 func (noBody) WriteTo(io.Writer) (int64, error) { return 0, nil } 108 109 var ( 110 // verify that an io.Copy from NoBody won't require a buffer: 111 _ io.WriterTo = NoBody 112 _ io.ReadCloser = NoBody 113 ) 114 115 // PushOptions describes options for Pusher.Push. 116 type PushOptions struct { 117 // Method specifies the HTTP method for the promised request. 118 // If set, it must be "GET" or "HEAD". Empty means "GET". 119 Method string 120 121 // Header specifies additional promised request headers. This cannot 122 // include HTTP/2 pseudo header fields like ":path" and ":scheme", 123 // which will be added automatically. 124 Header Header 125 } 126 127 // Pusher is the interface implemented by ResponseWriters that support 128 // HTTP/2 server push. For more background, see 129 // https://tools.ietf.org/html/rfc7540#section-8.2. 130 type Pusher interface { 131 // Push initiates an HTTP/2 server push. This constructs a synthetic 132 // request using the given target and options, serializes that request 133 // into a PUSH_PROMISE frame, then dispatches that request using the 134 // server's request handler. If opts is nil, default options are used. 135 // 136 // The target must either be an absolute path (like "/path") or an absolute 137 // URL that contains a valid host and the same scheme as the parent request. 138 // If the target is a path, it will inherit the scheme and host of the 139 // parent request. 140 // 141 // The HTTP/2 spec disallows recursive pushes and cross-authority pushes. 142 // Push may or may not detect these invalid pushes; however, invalid 143 // pushes will be detected and canceled by conforming clients. 144 // 145 // Handlers that wish to push URL X should call Push before sending any 146 // data that may trigger a request for URL X. This avoids a race where the 147 // client issues requests for X before receiving the PUSH_PROMISE for X. 148 // 149 // Push will run in a separate goroutine making the order of arrival 150 // non-deterministic. Any required synchronization needs to be implemented 151 // by the caller. 152 // 153 // Push returns ErrNotSupported if the client has disabled push or if push 154 // is not supported on the underlying connection. 155 Push(target string, opts *PushOptions) error 156 } 157