How Go 1.26 Enables Direct Creation and Management of HTTP Client Connections

Background

The current http.Transport maintains a pool of connections that may serve multiple servers and support both HTTP/1 and HTTP/2. However, Transport does not expose any way to manipulate a single connection directly, which makes it impossible for callers that need fine‑grained control.

New API Design

The proposal introduces a NewClientConn method on Transport that creates a dedicated client connection. The method signature is:

func (t *Transport) NewClientConn(ctx context.Context, scheme, address string) (*ClientConn, error)

It returns a ClientConn object that is not added to the transport’s connection pool and is not used by Transport.RoundTrip.

NewClientConn creates a connection

Example usage:

transport := &http.Transport{MaxIdleConns: 100}
conn, err := transport.NewClientConn(context.Background(), "https", "example.com:443")
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

req, _ := http.NewRequest("GET", "https://example.com/api", nil)
resp, err := conn.RoundTrip(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

ClientConn type

ClientConn

represents a single client connection. Its key method is:

func (cc *ClientConn) RoundTrip(*http.Request) (*http.Response, error)

Unlike Transport, which manages many connections, ClientConn manages exactly one.

Concurrency control design

The proposal adds two methods to handle request concurrency:

func (cc *ClientConn) RequestLimit() int64          // total number of requests that may be sent (including completed ones)
func (cc *ClientConn) RequestsCompleted() int64    // number of requests that have finished

RequestLimit

is monotonic; it does not decrease when a request is in flight, but increases when a request completes.

HTTP/1 connection example

conn, _ := transport.NewClientConn(ctx, "http", "example.com:80")
fmt.Println("Initial RequestLimit:", conn.RequestLimit()) // 1
req1, _ := http.NewRequest("GET", "http://example.com/api/1", nil)
resp1, _ := conn.RoundTrip(req1)
fmt.Println("During request RequestLimit:", conn.RequestLimit()) // still 1
io.Copy(io.Discard, resp1.Body)
resp1.Body.Close()
fmt.Println("After completion RequestLimit:", conn.RequestLimit()) // 2
fmt.Println("RequestsCompleted:", conn.RequestsCompleted()) // 1

HTTP/2 connection example

conn, _ := transport.NewClientConn(ctx, "https", "example.com:443")
fmt.Println("Initial RequestLimit:", conn.RequestLimit()) // e.g., 100 (server limit)
var wg sync.WaitGroup
for i := 0; i < 50; i++ {
    wg.Add(1)
    go func(id int) {
        defer wg.Done()
        req, _ := http.NewRequest("GET", fmt.Sprintf("https://example.com/api/%d", id), nil)
        resp, _ := conn.RoundTrip(req)
        io.Copy(io.Discard, resp.Body)
        resp.Body.Close()
    }(i)
}
wg.Wait()
fmt.Println("After 50 requests RequestLimit:", conn.RequestLimit()) // 150
fmt.Println("RequestsCompleted:", conn.RequestsCompleted()) // 50
available := conn.RequestLimit() - 150 // example calculation
fmt.Printf("Can send %d more concurrent requests
", available)

State hook

The API also provides a hook that is called whenever the connection’s state changes:

func (cc *ClientConn) SetStateHook(f func(*ClientConn))

Example:

conn, _ := transport.NewClientConn(ctx, "https", "example.com:443")
conn.SetStateHook(func(cc *http.ClientConn) {
    fmt.Printf("State change – RequestLimit: %d, Completed: %d, Err: %v
", cc.RequestLimit(), cc.RequestsCompleted(), cc.Err())
})
req, _ := http.NewRequest("GET", "https://example.com/api", nil)
resp, _ := conn.RoundTrip(req)
resp.Body.Close()

Why NewClientConn is a Transport method?

Because http.Transport bundles both client‑side configuration (TLS settings, proxy, dialer, etc.) and connection‑pool management. Making NewClientConn a method on Transport lets the new connection automatically inherit all those custom settings without duplication.

Summary

The proposal solves a long‑standing pain point by giving developers a way to create and manage independent HTTP client connections via Transport.NewClientConn. It will be available in Go 1.26, bringing finer control over connection lifecycles, concurrency limits, and state monitoring.