http2: deprecate write schedulers

The user-provided write scheduler mechanism provides too
much visibility into implementation internals, is difficult
to use, and limits our ability to improve performance.

Fixes golang/go#67817

Change-Id: Iac02c0902f805b671b4541a5dd7eafe76a6a6964
Reviewed-on: https://go-review.googlesource.com/c/net/+/751640
Auto-Submit: Damien Neil <dneil@google.com>
Reviewed-by: Nicholas Husin <husin@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Nicholas Husin <nsh@golang.org>

Author: neild

http2/server.go

@@ -164,6 +164,8 @@ type Server struct {
 
 	// NewWriteScheduler constructs a write scheduler for a connection.
 	// If nil, a default scheduler is chosen.
+	//
+	// Deprecated: User-provided write schedulers are deprecated.
 	NewWriteScheduler func() WriteScheduler
 
 	// CountError, if non-nil, is called on HTTP/2 server errors.

http2/writesched.go

@@ -8,6 +8,8 @@ import "fmt"
 
 // WriteScheduler is the interface implemented by HTTP/2 write schedulers.
 // Methods are never called concurrently.
+//
+// Deprecated: User-provided write schedulers are deprecated.
 type WriteScheduler interface {
 	// OpenStream opens a new stream in the write scheduler.
 	// It is illegal to call this with streamID=0 or with a streamID that is
@@ -38,6 +40,8 @@ type WriteScheduler interface {
 }
 
 // OpenStreamOptions specifies extra options for WriteScheduler.OpenStream.
+//
+// Deprecated: User-provided write schedulers are deprecated.
 type OpenStreamOptions struct {
 	// PusherID is zero if the stream was initiated by the client. Otherwise,
 	// PusherID names the stream that pushed the newly opened stream.
@@ -47,6 +51,8 @@ type OpenStreamOptions struct {
 }
 
 // FrameWriteRequest is a request to write a frame.
+//
+// Deprecated: User-provided write schedulers are deprecated.
 type FrameWriteRequest struct {
 	// write is the interface value that does the writing, once the
 	// WriteScheduler has selected this frame to write. The write

http2/writesched_priority_rfc7540.go

@@ -14,6 +14,8 @@ import (
 const priorityDefaultWeightRFC7540 = 15 // 16 = 15 + 1
 
 // PriorityWriteSchedulerConfig configures a priorityWriteScheduler.
+//
+// Deprecated: User-provided write schedulers are deprecated.
 type PriorityWriteSchedulerConfig struct {
 	// MaxClosedNodesInTree controls the maximum number of closed streams to
 	// retain in the priority tree. Setting this to zero saves a small amount
@@ -55,6 +57,9 @@ type PriorityWriteSchedulerConfig struct {
 // NewPriorityWriteScheduler constructs a WriteScheduler that schedules
 // frames by following HTTP/2 priorities as described in RFC 7540 Section 5.3.
 // If cfg is nil, default options are used.
+//
+// Deprecated: The RFC 7540 write scheduler has known bugs and performance issues,
+// and RFC 7540 prioritization was deprecated in RFC 9113.
 func NewPriorityWriteScheduler(cfg *PriorityWriteSchedulerConfig) WriteScheduler {
 	return newPriorityWriteSchedulerRFC7540(cfg)
 }

http2/writesched_random.go

@@ -10,6 +10,8 @@ import "math"
 // priorities. Control frames like SETTINGS and PING are written before DATA
 // frames, but if no control frames are queued and multiple streams have queued
 // HEADERS or DATA frames, Pop selects a ready stream arbitrarily.
+//
+// Deprecated: User-provided write schedulers are deprecated.
 func NewRandomWriteScheduler() WriteScheduler {
 	return &randomWriteScheduler{sq: make(map[uint32]*writeQueue)}
 }