http

README

Go+ HTTP transport capabilities

goforge.dev/goplus/std/http complements net/http with one client and server surface for HTTP/3, HTTP/2, and HTTP/1.1.

The route subpackage provides the Go+-authored typed routing layer: Pattern[p], Request[p], ParamKey[T,p], Handler[p], immutable indexed route sets, and capability-indexed middleware. It lowers to ordinary net/http.Handler values and is consumed by goforge.dev/chi without adding a router dependency to the standard module. The parent package's RouteHandler also feeds a checked handler directly into the existing HTTP/1.1, HTTP/2, and HTTP/3 server surface, providing the second independent production consumer.

// The first request uses HTTP/2 or HTTP/1.1 and learns an h3 Alt-Svc.
// Later requests use HTTP/3 while the advertisement remains valid.
response, err := http.Get("https://example.test/assays")

Get, Head, Post, PostForm, and DefaultClient use the shared zero-configuration transport. Use &http.Transport{} with your own net/http.Client when you need isolated caches or custom TLS settings.

Transport implements net/http.RoundTripper. In Auto mode it does not blindly probe UDP: it learns HTTP/3 origin capability from Alt-Svc, including alternate UDP ports, and preserves the original authority and TLS server name. If HTTP/3 becomes unavailable, replayable requests retry through Go's HTTP/2 or HTTP/1.1 transport. Unreplayable request bodies are never consumed by a speculative attempt. Certificate verification and caller cancellation errors are not treated as downgrade signals.

A failed H3 alternative is suppressed for five minutes, preventing an unchanged fallback Alt-Svc response from causing another failed UDP probe on every request. A newly advertised authority can be tried immediately, and explicit prior knowledge overrides the cooldown.

Use PriorKnowledge for origins whose HTTP/3 capability is configured out of band, HTTP3Only when fallback is forbidden, or HTTP2Or1Only to disable QUIC.

Server serves one net/http.Handler over HTTP/3 on QUIC/UDP and TLS-based HTTP/2 and HTTP/1.1 on TCP. It publishes the correct Alt-Svc port on TCP responses:

server := &http.Server{Handler: mux, TLSConfig: tlsConfig}
err := server.Serve(tcpListener, udpPacketConn)

The default backend supports RFC 9368 compatible version negotiation and RFC 9369 QUIC v2 as well as QUIC v1. The TCP side enables HTTP/2 and HTTP/1.1. Shutdown coordinates shutdown of both protocol families. HTTP3 customizes the default backend. Setting NativeHTTP3 opts into the experimental native v1 backend; NativeQUICConfig customizes it.

Documentation

Overview

Package http provides HTTP transport capabilities that complement net/http. Its Transport discovers HTTP/3 through Alt-Svc and safely falls back through net/http's HTTP/2 and HTTP/1.1 negotiation.

Index

• Variables
• func Get(url string) (*nethttp.Response, error)
• func Head(url string) (*nethttp.Response, error)
• func Post(url, contentType string, body io.Reader) (*nethttp.Response, error)
• func PostForm(target string, data url.Values) (*nethttp.Response, error)
• func RouteHandler(pattern route.Pattern, handler route.Handler) nethttp.Handler
• func WithHTTP3Capability(ctx context.Context) context.Context
• type Mode
• type Server
  • func (s *Server) Close() error
  • func (s *Server) Serve(tcp net.Listener, udp net.PacketConn) error
  • func (s *Server) Shutdown(ctx context.Context) error
• type Transport
  • func (t *Transport) CloseIdleConnections()
  • func (t *Transport) ForgetHTTP3(u *url.URL)
  • func (t *Transport) MarkHTTP3(u *url.URL, until time.Time)
  • func (t *Transport) ObserveAltSvc(u *url.URL, values []string, now time.Time)
  • func (t *Transport) RoundTrip(req *nethttp.Request) (*nethttp.Response, error)
  • func (t *Transport) SupportsHTTP3(u *url.URL) bool

Variables

var DefaultClient = &nethttp.Client{Transport: DefaultTransport}

DefaultClient is ready for ordinary HTTP use with automatic HTTP/3. Its methods have the same shape as net/http.Client.

var DefaultTransport = &Transport{}

DefaultTransport automatically learns HTTP/3 through Alt-Svc and safely falls back through HTTP/2 and HTTP/1.1. It is shared by DefaultClient.

Functions

func Get

func Get(url string) (*nethttp.Response, error)

Get uses DefaultClient, including automatic HTTP/3 discovery and fallback.

func Head

func Head(url string) (*nethttp.Response, error)

Head uses DefaultClient, including automatic HTTP/3 discovery and fallback.

func Post

func Post(url, contentType string, body io.Reader) (*nethttp.Response, error)

Post uses DefaultClient, including automatic HTTP/3 discovery and fallback.

func PostForm

func PostForm(target string, data url.Values) (*nethttp.Response, error)

PostForm uses DefaultClient, including automatic HTTP/3 discovery and fallback.

func RouteHandler

func RouteHandler(pattern route.Pattern, handler route.Handler) nethttp.Handler

RouteHandler bridges the pattern-indexed std/http/route layer into the protocol-negotiating Server. Go+ checks Pattern[p] and Handler[p] before erasure; ordinary Go receives the retained runtime boundary guard.

func WithHTTP3Capability

func WithHTTP3Capability(ctx context.Context) context.Context

WithHTTP3Capability returns a context carrying no mutable state; it exists as a semantic marker for callers that explicitly choose PriorKnowledge.

Types

type Mode

type Mode uint8

Mode controls transport selection.

const (
	// Auto uses HTTP/3 for origins learned through Alt-Svc (or when
	// PriorKnowledge is enabled), falling back to HTTP/2 or HTTP/1.1.
	Auto Mode = iota
	// HTTP3Only requires HTTP/3 and never falls back.
	HTTP3Only
	// HTTP2Or1Only disables HTTP/3.
	HTTP2Or1Only
)

type Server

type Server struct {
	Handler          nethttp.Handler
	TLSConfig        *tls.Config
	QUICConfig       *quic.Config
	NativeQUICConfig *nativehttp3.RFC9000Config
	// XQUICConfig is retained for compatibility. NativeQUICConfig takes
	// precedence when both are set.
	// Deprecated: use NativeQUICConfig.
	XQUICConfig *nativehttp3.RFC9000Config

	HTTP *nethttp.Server
	// NativeHTTP3 opts into and customizes the experimental native server.
	// When both HTTP3 and NativeHTTP3 are nil, the RFC 9368/9369-capable
	// quic-go server is used so QUIC v1 and v2 work out of the box.
	NativeHTTP3 *nativehttp3.NativeServer
	// HTTP3 customizes the default quic-go server.
	HTTP3 *refhttp3.Server
	// contains filtered or unexported fields
}

Server serves one net/http Handler over HTTP/3 and TLS-based HTTP/2 or HTTP/1.1. The zero value requires TLSConfig to be set before Serve.

func (*Server) Close

func (s *Server) Close() error

Close immediately closes servers and their listeners.

func (*Server) Serve

func (s *Server) Serve(tcp net.Listener, udp net.PacketConn) error

Serve serves TLS/TCP on tcp and QUIC on udp until either server fails or Shutdown is called. It advertises the UDP port in Alt-Svc on TCP responses. Serve owns and closes both listeners.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down both protocol families.

type Transport

type Transport struct {
	Mode Mode

	// PriorKnowledge tries HTTP/3 for every HTTPS origin before an Alt-Svc
	// advertisement has been observed.
	PriorKnowledge bool

	TLSClientConfig *tls.Config
	QUICConfig      *quic.Config

	// HTTP3 and Fallback permit shared or instrumented transports. Nil values
	// use an HTTP/3 transport and net/http.DefaultTransport respectively.
	HTTP3    nethttp.RoundTripper
	Fallback nethttp.RoundTripper
	// contains filtered or unexported fields
}

Transport implements net/http.RoundTripper with HTTP/3 -> HTTP/2 -> HTTP/1.1 selection. The zero value is ready for use.

func (*Transport) CloseIdleConnections

func (t *Transport) CloseIdleConnections()

CloseIdleConnections closes idle connections owned by both transport tiers.

func (*Transport) ForgetHTTP3

func (t *Transport) ForgetHTTP3(u *url.URL)

ForgetHTTP3 removes learned capability after a failed HTTP/3 attempt.

func (*Transport) MarkHTTP3

func (t *Transport) MarkHTTP3(u *url.URL, until time.Time)

MarkHTTP3 records prior knowledge for an origin until the supplied time.

func (*Transport) ObserveAltSvc

func (t *Transport) ObserveAltSvc(u *url.URL, values []string, now time.Time)

ObserveAltSvc records an h3 alternative, including an alternative host or UDP port, while retaining the origin host for TLS verification and HTTP authority.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *nethttp.Request) (*nethttp.Response, error)

RoundTrip implements net/http.RoundTripper.

func (*Transport) SupportsHTTP3

func (t *Transport) SupportsHTTP3(u *url.URL) bool

SupportsHTTP3 reports whether HTTP/3 capability is currently cached for u.