Documentation
¶
Overview ¶
Package wt serves and dials webdial connections over WebTransport (HTTP/3).
It is a separate package so that programs using only the WebSocket and SSE transports do not link quic-go. Nothing in the root webdial package imports this one; the dependency runs strictly the other way.
A session carries exactly one client-initiated bidirectional stream, and that stream is the net.Conn. Latency probes travel over WebTransport datagrams as "ping:<ts>"/"pong:<ts>", the same control vocabulary the WebSocket transport puts in text frames.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Dialer ¶
type Dialer struct {
// TLSConfig configures the QUIC handshake. Use it to trust a development
// certificate. Nil means the host's root CAs.
//
// The h3 ALPN is appended when NextProtos does not already contain it:
// WebTransport cannot negotiate anything else, and a config carrying only
// unrelated protocols would otherwise fail the handshake obscurely.
TLSConfig *tls.Config
// QUICConfig, when non-nil, is the base QUIC configuration. The extensions
// WebTransport requires are applied to a copy.
QUICConfig *quic.Config
// KeepAlive sets the QUIC keep-alive period. Zero leaves it to QUICConfig.
KeepAlive time.Duration
}
Dialer configures WebTransport dials. The zero value is usable.
func (*Dialer) Dial ¶
Dial establishes a webdial connection over WebTransport. baseURL must be an http or https URL; http is promoted to https, since WebTransport has no cleartext form. Note that the HTTP/3 endpoint commonly listens on a different port from the HTTP endpoint, even when the path is identical.
As with net.Dialer.DialContext, ctx governs establishment only: it does not carry over to the returned connection.
type Server ¶
type Server struct {
// Addr is the UDP address ListenAndServe listens on. Empty means ":443".
Addr string
// TLSConfig is the server certificate. WebTransport is HTTPS only. The h3
// ALPN is added automatically when absent.
TLSConfig *tls.Config
// Handler is served over HTTP/3. Nil serves s, which answers WebTransport
// itself and delegates every other request to the core server, so a single
// endpoint also serves the SSE fallback over HTTP/3.
Handler http.Handler
// CheckOrigin mirrors webdial.Server.CheckOrigin. Nil uses the same secure
// default: a request whose Origin host does not match Host is rejected,
// while a request without an Origin is accepted.
CheckOrigin func(*http.Request) bool
// KeepAlive overrides the QUIC keep-alive period. Zero inherits the core
// server's KeepAliveInterval. Negative disables QUIC keep-alives.
//
// Unlike SSE, WebTransport has no webdial-level server heartbeat: QUIC
// PING frames refresh the UDP path, which is what a keep-alive is for
// here. This matches the WebSocket transport, whose heartbeat is also a
// protocol-level ping invisible to the application.
KeepAlive time.Duration
// QUICConfig, when non-nil, is the base QUIC configuration. The extensions
// WebTransport requires are applied to a copy, so the caller's value is
// left untouched.
QUICConfig *quic.Config
// contains filtered or unexported fields
}
Server serves webdial connections over WebTransport. Accepted connections go to the core webdial.Server, so one Accept loop serves every transport.
WebTransport needs an HTTP/3 listener, which is separate from the TCP listener serving the WebSocket and SSE transports. A Server owns that listener: WebTransport sessions are tracked per QUIC connection, so the accept loop cannot be delegated to a plain http3.Server. Callers with their own QUIC listener can drive ServeQUICConn directly.
The zero value is not usable; call NewServer. Exported fields must be set before the first call to ListenAndServe, Serve, ServeQUICConn or ServeHTTP.
func (*Server) Close ¶
Close stops the listener and closes established sessions. It does not close the core webdial.Server.
func (*Server) ListenAndServe ¶
ListenAndServe listens for QUIC on Addr and serves HTTP/3.
func (*Server) Serve ¶
func (s *Server) Serve(conn net.PacketConn) error
Serve serves HTTP/3 on an existing packet connection, which is how callers that need an ephemeral port get an address up front.
func (*Server) ServeHTTP ¶
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP upgrades WebTransport CONNECT requests and pushes the resulting connections to the core server. Every other request is delegated to the core server unchanged.
Routing keys on the method alone. The extended-CONNECT protocol token changed between drafts, so validating it here would pin webdial to one of them; Upgrade checks the method, the token and the origin itself.
Source Files