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 nettrace contains internal hooks for tracing activity in
6// the net package. This package is purely internal for use by the
7// net/http/httptrace package and has no stable API exposed to end
8// users.
9package nettrace
10
11// TraceKey is a context.Context Value key. Its associated value should
12// be a *Trace struct.
13type TraceKey struct{}
14
15// LookupIPAltResolverKey is a context.Context Value key used by tests to
16// specify an alternate resolver func.
17// It is not exposed to outsider users. (But see issue 12503)
18// The value should be the same type as lookupIP:
19//
20//	func lookupIP(ctx context.Context, host string) ([]IPAddr, error)
21type LookupIPAltResolverKey struct{}
22
23// Trace contains a set of hooks for tracing events within
24// the net package. Any specific hook may be nil.
25type Trace struct {
26	// DNSStart is called with the hostname of a DNS lookup
27	// before it begins.
28	DNSStart func(name string)
29
30	// DNSDone is called after a DNS lookup completes (or fails).
31	// The coalesced parameter is whether singleflight de-duped
32	// the call. The addrs are of type net.IPAddr but can't
33	// actually be for circular dependency reasons.
34	DNSDone func(netIPs []any, coalesced bool, err error)
35
36	// ConnectStart is called before a Dial, excluding Dials made
37	// during DNS lookups. In the case of DualStack (Happy Eyeballs)
38	// dialing, this may be called multiple times, from multiple
39	// goroutines.
40	ConnectStart func(network, addr string)
41
42	// ConnectDone is called after a Dial with the results, excluding
43	// Dials made during DNS lookups. It may also be called multiple
44	// times, like ConnectStart.
45	ConnectDone func(network, addr string, err error)
46}
47