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 httptrace provides mechanisms to trace the events within 6 // HTTP client requests. 7 package httptrace 8 9 import ( 10 "context" 11 "crypto/tls" 12 "internal/nettrace" 13 "net" 14 "net/textproto" 15 "reflect" 16 "time" 17 ) 18 19 // unique type to prevent assignment. 20 type clientEventContextKey struct{} 21 22 // ContextClientTrace returns the ClientTrace associated with the 23 // provided context. If none, it returns nil. 24 func ContextClientTrace(ctx context.Context) *ClientTrace { 25 trace, _ := ctx.Value(clientEventContextKey{}).(*ClientTrace) 26 return trace 27 } 28 29 // WithClientTrace returns a new context based on the provided parent 30 // ctx. HTTP client requests made with the returned context will use 31 // the provided trace hooks, in addition to any previous hooks 32 // registered with ctx. Any hooks defined in the provided trace will 33 // be called first. 34 func WithClientTrace(ctx context.Context, trace *ClientTrace) context.Context { 35 if trace == nil { 36 panic("nil trace") 37 } 38 old := ContextClientTrace(ctx) 39 trace.compose(old) 40 41 ctx = context.WithValue(ctx, clientEventContextKey{}, trace) 42 if trace.hasNetHooks() { 43 nt := &nettrace.Trace{ 44 ConnectStart: trace.ConnectStart, 45 ConnectDone: trace.ConnectDone, 46 } 47 if trace.DNSStart != nil { 48 nt.DNSStart = func(name string) { 49 trace.DNSStart(DNSStartInfo{Host: name}) 50 } 51 } 52 if trace.DNSDone != nil { 53 nt.DNSDone = func(netIPs []interface{}, coalesced bool, err error) { 54 addrs := make([]net.IPAddr, len(netIPs)) 55 for i, ip := range netIPs { 56 addrs[i] = ip.(net.IPAddr) 57 } 58 trace.DNSDone(DNSDoneInfo{ 59 Addrs: addrs, 60 Coalesced: coalesced, 61 Err: err, 62 }) 63 } 64 } 65 ctx = context.WithValue(ctx, nettrace.TraceKey{}, nt) 66 } 67 return ctx 68 } 69 70 // ClientTrace is a set of hooks to run at various stages of an outgoing 71 // HTTP request. Any particular hook may be nil. Functions may be 72 // called concurrently from different goroutines and some may be called 73 // after the request has completed or failed. 74 // 75 // ClientTrace currently traces a single HTTP request & response 76 // during a single round trip and has no hooks that span a series 77 // of redirected requests. 78 // 79 // See https://blog.golang.org/http-tracing for more. 80 type ClientTrace struct { 81 // GetConn is called before a connection is created or 82 // retrieved from an idle pool. The hostPort is the 83 // "host:port" of the target or proxy. GetConn is called even 84 // if there's already an idle cached connection available. 85 GetConn func(hostPort string) 86 87 // GotConn is called after a successful connection is 88 // obtained. There is no hook for failure to obtain a 89 // connection; instead, use the error from 90 // Transport.RoundTrip. 91 GotConn func(GotConnInfo) 92 93 // PutIdleConn is called when the connection is returned to 94 // the idle pool. If err is nil, the connection was 95 // successfully returned to the idle pool. If err is non-nil, 96 // it describes why not. PutIdleConn is not called if 97 // connection reuse is disabled via Transport.DisableKeepAlives. 98 // PutIdleConn is called before the caller's Response.Body.Close 99 // call returns. 100 // For HTTP/2, this hook is not currently used. 101 PutIdleConn func(err error) 102 103 // GotFirstResponseByte is called when the first byte of the response 104 // headers is available. 105 GotFirstResponseByte func() 106 107 // Got100Continue is called if the server replies with a "100 108 // Continue" response. 109 Got100Continue func() 110 111 // Got1xxResponse is called for each 1xx informational response header 112 // returned before the final non-1xx response. Got1xxResponse is called 113 // for "100 Continue" responses, even if Got100Continue is also defined. 114 // If it returns an error, the client request is aborted with that error value. 115 Got1xxResponse func(code int, header textproto.MIMEHeader) error 116 117 // DNSStart is called when a DNS lookup begins. 118 DNSStart func(DNSStartInfo) 119 120 // DNSDone is called when a DNS lookup ends. 121 DNSDone func(DNSDoneInfo) 122 123 // ConnectStart is called when a new connection's Dial begins. 124 // If net.Dialer.DualStack (IPv6 "Happy Eyeballs") support is 125 // enabled, this may be called multiple times. 126 ConnectStart func(network, addr string) 127 128 // ConnectDone is called when a new connection's Dial 129 // completes. The provided err indicates whether the 130 // connection completed successfully. 131 // If net.Dialer.DualStack ("Happy Eyeballs") support is 132 // enabled, this may be called multiple times. 133 ConnectDone func(network, addr string, err error) 134 135 // TLSHandshakeStart is called when the TLS handshake is started. When 136 // connecting to an HTTPS site via an HTTP proxy, the handshake happens 137 // after the CONNECT request is processed by the proxy. 138 TLSHandshakeStart func() 139 140 // TLSHandshakeDone is called after the TLS handshake with either the 141 // successful handshake's connection state, or a non-nil error on handshake 142 // failure. 143 TLSHandshakeDone func(tls.ConnectionState, error) 144 145 // WroteHeaderField is called after the Transport has written 146 // each request header. At the time of this call the values 147 // might be buffered and not yet written to the network. 148 WroteHeaderField func(key string, value []string) 149 150 // WroteHeaders is called after the Transport has written 151 // all request headers. 152 WroteHeaders func() 153 154 // Wait100Continue is called if the Request specified 155 // "Expect: 100-continue" and the Transport has written the 156 // request headers but is waiting for "100 Continue" from the 157 // server before writing the request body. 158 Wait100Continue func() 159 160 // WroteRequest is called with the result of writing the 161 // request and any body. It may be called multiple times 162 // in the case of retried requests. 163 WroteRequest func(WroteRequestInfo) 164 } 165 166 // WroteRequestInfo contains information provided to the WroteRequest 167 // hook. 168 type WroteRequestInfo struct { 169 // Err is any error encountered while writing the Request. 170 Err error 171 } 172 173 // compose modifies t such that it respects the previously-registered hooks in old, 174 // subject to the composition policy requested in t.Compose. 175 func (t *ClientTrace) compose(old *ClientTrace) { 176 if old == nil { 177 return 178 } 179 tv := reflect.ValueOf(t).Elem() 180 ov := reflect.ValueOf(old).Elem() 181 structType := tv.Type() 182 for i := 0; i < structType.NumField(); i++ { 183 tf := tv.Field(i) 184 hookType := tf.Type() 185 if hookType.Kind() != reflect.Func { 186 continue 187 } 188 of := ov.Field(i) 189 if of.IsNil() { 190 continue 191 } 192 if tf.IsNil() { 193 tf.Set(of) 194 continue 195 } 196 197 // Make a copy of tf for tf to call. (Otherwise it 198 // creates a recursive call cycle and stack overflows) 199 tfCopy := reflect.ValueOf(tf.Interface()) 200 201 // We need to call both tf and of in some order. 202 newFunc := reflect.MakeFunc(hookType, func(args []reflect.Value) []reflect.Value { 203 tfCopy.Call(args) 204 return of.Call(args) 205 }) 206 tv.Field(i).Set(newFunc) 207 } 208 } 209 210 // DNSStartInfo contains information about a DNS request. 211 type DNSStartInfo struct { 212 Host string 213 } 214 215 // DNSDoneInfo contains information about the results of a DNS lookup. 216 type DNSDoneInfo struct { 217 // Addrs are the IPv4 and/or IPv6 addresses found in the DNS 218 // lookup. The contents of the slice should not be mutated. 219 Addrs []net.IPAddr 220 221 // Err is any error that occurred during the DNS lookup. 222 Err error 223 224 // Coalesced is whether the Addrs were shared with another 225 // caller who was doing the same DNS lookup concurrently. 226 Coalesced bool 227 } 228 229 func (t *ClientTrace) hasNetHooks() bool { 230 if t == nil { 231 return false 232 } 233 return t.DNSStart != nil || t.DNSDone != nil || t.ConnectStart != nil || t.ConnectDone != nil 234 } 235 236 // GotConnInfo is the argument to the ClientTrace.GotConn function and 237 // contains information about the obtained connection. 238 type GotConnInfo struct { 239 // Conn is the connection that was obtained. It is owned by 240 // the http.Transport and should not be read, written or 241 // closed by users of ClientTrace. 242 Conn net.Conn 243 244 // Reused is whether this connection has been previously 245 // used for another HTTP request. 246 Reused bool 247 248 // WasIdle is whether this connection was obtained from an 249 // idle pool. 250 WasIdle bool 251 252 // IdleTime reports how long the connection was previously 253 // idle, if WasIdle is true. 254 IdleTime time.Duration 255 } 256