package httptrack

Import Path
	go.pact.im/x/httptrack (on go.dev)

Dependency Relation
	imports 4 packages, and imported by one package

Involved Source Files

	    conn.go
	  d doc.go
		Package httptrack provides tools for tracking HTTP connection state
		transitions.
		
		It integrates with [net/http.Server] via the ConnState hook to support:
		  - Graceful shutdowns (via [ConnTracker])
		  - Connection statistics (via [StatsTracker])
		
		Trackers implement the [Tracker] interface and can be composed using
		[Compose] function.

	    stats.go
	    tracker.go
Code Examples

	ConnTracker
		package main
		
		import (
			"net/http"
		
			"go.pact.im/x/httptrack"
		)
		
		func main() {
			server := &http.Server{}
		
			var connTracker httptrack.ConnTracker
			server.ConnState = connTracker.Track
		
			// On shutdown:
			_ = server.Close()
			connTracker.Wait() // blocks until all connections are done
		}

	StatsTracker
		package main
		
		import (
			"fmt"
			"net/http"
		
			"go.pact.im/x/httptrack"
		)
		
		func main() {
			server := &http.Server{}
		
			var statsTracker httptrack.StatsTracker
			server.ConnState = statsTracker.Track
		
			stats := statsTracker.Stats()
			fmt.Println(
				"Active:", stats.Active(),
				"Idle:", stats.Idle(),
				"Closed:", stats.ClosedTotal(),
			)
		}

	Wrap
		package main
		
		import (
			"net/http"
		
			"go.pact.im/x/httptrack"
		)
		
		func main() {
			server := &http.Server{}
		
			var connTracker httptrack.ConnTracker
			var statsTracker httptrack.StatsTracker
		
			httptrack.Wrap(server, httptrack.Compose(
				&statsTracker,
				&connTracker,
			))
		}


Package-Level Type Names (total 5, all are exported)

	/* sort exporteds by: alphabet | popularity */
	 type ConnTracker (struct)
		ConnTracker is a connection tracker for HTTP connections. It can be
		used to wait for all existing HTTP connections to finish after performing
		HTTP server shutdown.
		
		Note that [http.Server.Close] closes all connections but does not wait for
		per-connection goroutines to return. If the connection was active, it is up
		to the running [http.Handler] to handle connection error and eventually
		return. ConnTracker allows waiting for all in-flight handlers.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			wg sync.WaitGroup
		Methods (total 2, both are exported)
			(*ConnTracker) Track(_ net.Conn, state http.ConnState)
				Track updates the connection counter based on the connection’s state.
				It should be assigned to the ConnState field of an [http.Server].

			(*ConnTracker) Wait()
				Wait blocks until all tracked HTTP connections have completed. It should be
				called after [http.Server.Serve] has returned.

		Implements (at least one exported)
			*ConnTracker : Tracker

	 type Stats (struct)
		Stats holds a snapshot of HTTP connection state statistics.

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			counter [5]uint64
			gauge [3]uint
		Methods (total 8, all are exported)
			(*Stats) Accepted() uint
				Accepted returns the number of connections currently in the [http.StateNew]
				state.
				
				A non-zero value typically indicates that there are accepted connections
				which have not yet sent a complete HTTP request. This may occur naturally
				under normal traffic, but a persistently high number of connections in this
				state can suggest:
				
				  - Slow or high-latency clients
				  - Clients intentionally delaying requests (e.g. denial-of-service attack)
				  - Server under heavy load or accepting connections faster than it can
				    process them

			(*Stats) AcceptedTotal() uint64
				AcceptedTotal returns the total number of connections ever seen in the
				[http.StateNew] state.
				
				This is a monotonically increasing counter that reflects the cumulative
				number of accepted connections. It includes all connections, regardless of
				whether they were later closed, hijacked, or reused.

			(*Stats) Active() uint
				Active returns the number of connections currently in the [http.StateActive]
				state.
				
				In HTTP/1.x, this usually means that a request is currently being processed.
				
				In HTTP/2, this state indicates that the connection has at least one open
				stream. However, the connection may briefly enter the Active state after
				being accepted as part of reading the HTTP/2 connection preface, before
				transitioning to Idle state. Therefore, a connection in the Active state
				is not guaranteed to be actively handling a request.

			(*Stats) ActiveTotal() uint64
				ActiveTotal returns the total number of times connections have transitioned
				into the [http.StateActive] state.
				
				This counter increases every time a connection becomes active. It does not
				represent the number of requests, since a single connection may enter Active
				state for multiple requests (e.g. HTTP/2 streams).

			(*Stats) ClosedTotal() uint64
				ClosedTotal returns the number of connections that have been closed.
				
				A non-zero Closed count indicates connections that have been fully closed
				by either the server or the client, including normal connection termination
				and error scenarios.
				
				High numbers in Closed are typical over time, but a sudden spike may
				indicate:
				
				  - Mass client disconnects
				  - Server-side timeouts or errors
				  - Deployment cycles or load balancer resets

			(*Stats) HijackedTotal() uint64
				HijackedTotal returns the number of connections that have been hijacked via
				[http.Hijacker].
				
				A hijacked connection is taken over by the application (e.g. for WebSocket
				upgrade) and is no longer managed by the HTTP server.

			(*Stats) Idle() uint
				Idle returns the number of connections currently in the [http.StateIdle]
				state.
				
				In HTTP/1.x, Idle connections are typically those that have completed
				a request and are being kept alive. A non-zero Idle count is normal in
				servers that support HTTP keep-alive.
				
				In HTTP/2, this state indicates that the connection has no open streams.
				A newly established HTTP/2 connection enters the Idle state after reading
				the connection preface.

			(*Stats) IdleTotal() uint64
				IdleTotal returns the total number of times connections have entered the
				[http.StateIdle] state.

		As Outputs Of (at least one exported)
			func (*StatsTracker).Stats() Stats

	 type StatsTracker (struct)
		StatsTracker is a [Tracker] implementation that keeps counts of HTTP
		connections in each state. It can be used for monitoring connections
		and their lifecycle.

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			conns map[net.Conn]http.ConnState
			mu sync.Mutex
			stats Stats
		Methods (total 3, all are exported)
			(*StatsTracker) Connections() map[net.Conn]http.ConnState
				Connections returns a snapshot of connection states.

			(*StatsTracker) Stats() Stats
				Stats returns a snapshot of connection statistics.

			(*StatsTracker) Track(conn net.Conn, state http.ConnState)
				Track records the transition of a connection’s state. It updates internal
				statistics and tracks the current state of each connection.
				
				The dynamic type of the provided net.Conn must be comparable (i.e. usable as
				a map key). Most standard connection types (such as tls.Conn pointer) meet
				this requirement. Passing a non-comparable type will cause a runtime panic.

		Implements (at least one exported)
			*StatsTracker : Tracker

	 type Tracker (interface)
		Tracker is an interface for tracking HTTP connection state transitions.
		It matches the signature required by [http.Server.ConnState], allowing
		implementations to observe and respond to connection lifecycle events.

		Methods (only one, which is exported)
			( Tracker) Track(net.Conn, http.ConnState)
		Implemented By (at least 3, all are exported)
			*ConnTracker
			*StatsTracker
			 TrackerFunc
		As Inputs Of (at least 2, both are exported)
			func Compose(hooks ...Tracker) TrackerFunc
			func Wrap(s *http.Server, h Tracker) TrackerFunc

	 type TrackerFunc (func)
		TrackerFunc is an adapter to allow the use of ordinary functions as
		[Tracker] implementations. If f is a function with the appropriate
		signature, TrackerFunc(f) is a [Tracker] that calls f.

		Methods (only one, which is exported)
			( TrackerFunc) Track(conn net.Conn, state http.ConnState)
				Track calls f(conn, state).

		Implements (at least one exported)
			 TrackerFunc : Tracker
		As Outputs Of (at least 2, both are exported)
			func Compose(hooks ...Tracker) TrackerFunc
			func Wrap(s *http.Server, h Tracker) TrackerFunc


Package-Level Functions (total 2, both are exported)

	 func Compose(hooks ...Tracker) TrackerFunc
		Compose returns a TrackerFunc that invokes multiple [Tracker] hooks. Each call
		to Track on the returned TrackerFunc will call Track on all provided Tracker
		implementations, in the order they are passed.
		
		When using a [ConnTracker] for graceful shutdown, it should be passed
		as the last argument to Compose. This ensures that other trackers have
		completed their processing before the server is allowed to shut down.

	 func Wrap(s *http.Server, h Tracker) TrackerFunc
		Wrap configures an [http.Server] to use the given [Tracker] via server’s
		ConnState hook. If ConnState is already set, it is preserved and runs before
		the provided [Tracker], and Wrap returns the old value.


Package-Level Constants (total 2, neither is exported)

	/* 2 unexporteds ... *//* 2 unexporteds: */
	const counterSize http.ConnState = 5 // all states
		counterSize is the count of [http.ConnState] states that are used for
		counter-based statistics.

	const gaugeSize http.ConnState = 3 // non-terminal states
		gaugeSize is the count of [http.ConnState] states that are used for
		gauge-based statistics.

The pages are generated with Golds v0.7.6. (GOOS=linux GOARCH=amd64)