Proposal: clarify Upgrader vs Server responsibilities

[okdaichi]

Motivation

The main reason for this proposal is to reduce coupling between two different concerns:

1. transport/connection serving lifecycle (Server, Serve, ServeQUICConn)
2. request handshake/session-upgrade logic (Upgrade)

In practice, keeping both on Server means callers often need to retain a Server instance just to perform upgrades in handlers, even when they don’t need the full serving lifecycle there.

Proposed direction

• Keep upgrade/session-establishment logic centered in Upgrader.
• Keep Server focused on serving/lifecycle responsibilities.
• Keep Server.Upgrade as a compatibility shim so migration can be gradual.

This makes the boundary explicit and simplifies handler-side usage.

Practical benefit

This also enables more flexible route-level configuration (for example, per-path ApplicationProtocols by using different Upgrader instances), which is harder to express cleanly when Upgrade only lives on Server.

API design consistency

This direction is also similar to the API shape in gorilla/websocket, where upgrade logic is exposed via a dedicated Upgrader type.
Reference: https://github.com/gorilla/websocket/blob/main/server.go

[okdaichi]

Minimal example

Current pattern (upgrade coupled to Server):

mux := http.NewServeMux()
s := &webtransport.Server{
    H3: &http3.Server{
        Addr:    ":4433",
        Handler: mux,
    },
}

mux.HandleFunc("/wt", func(w http.ResponseWriter, r *http.Request) {
    sess, err := s.Upgrade(w, r) // Need to retain `s` here
    if err != nil {
        // handle error
        return
    }
    _ = sess
})

_ = s.ListenAndServe()

Proposed pattern (upgrade logic explicit via Upgrader):

mux := http.NewServeMux()
s := &webtransport.Server{
    H3: &http3.Server{
        Addr:    ":4433",
        Handler: mux,
    },
}

upgraderA := webtransport.Upgrader{
    ApplicationProtocols: []string{"my-proto-a"},
}
upgraderB := webtransport.Upgrader{
    ApplicationProtocols: []string{"my-proto-b"},
}

mux.HandleFunc("/wt-a", func(w http.ResponseWriter, r *http.Request) {
    sess, err := upgraderA.Upgrade(w, r)
    if err != nil {
        // handle error
        return
    }
    _ = sess
})

mux.HandleFunc("/wt-b", func(w http.ResponseWriter, r *http.Request) {
    sess, err := upgraderB.Upgrade(w, r)
    if err != nil {
        // handle error
        return
    }
    _ = sess
})

_ = s.ListenAndServe()

This makes the boundary clearer (Server for serving lifecycle, Upgrader for session upgrade),
and enables route-level policy (e.g., per-route ApplicationProtocols) by using different Upgrader configs.