http3: RFC 9218 - Extensible Priority Scheme

[chanh1964]

Hello developers.

Is there any work to implement RFC 9218 to quic-go?
I'm actually interested in (and in need of) such a work.

I guess I can give it a try if no work exists.
In that case, is there any hint on the files I should start with?

Thank you very much in advance.

[marten-seemann]

Sorry for the late response!

There's currently nobody working on implementing on RFC 9218, but such work would be highly appreciated!
Please comment on this thread if you're interested to submit a PR, then we can discuss the design.

[marten-seemann]

Chrome is planning to implement this feature: https://groups.google.com/a/chromium.org/g/blink-dev/c/eEeDzwtw5v0/m/wYqhn46XBQAJ

[SahibYar]

Hi @marten-seemann thank you for pointing to this in #3870

In reference to #437 "Dependency Weighing" mentioned in RFC-7540 is already deprecated as explain in RFC9218 in Motivation for Replacing RFC 7540 Stream Priorities and here

The design and implementation of RFC 7540 stream priority were observed to have shortcomings, as explained in Section 2. HTTP/2 [HTTP/2] has consequently deprecated the use of these stream priority signals.

I have just started understanding QUIC and quic-go and want to implement Stream prioritization.

I was reading RFC9000 which tells

Sending the first STREAM or STREAM_DATA_BLOCKED frame causes a sending part of a stream to enter the "Send" state. An implementation might choose to defer allocating a stream ID to a stream until it sends the first STREAM frame and enters this state, which can allow for better stream prioritization.

and

Endpoints SHOULD prioritize retransmission of data over sending new data, unless priorities specified by the application indicate otherwise;

and

A QUIC implementation SHOULD provide ways in which an application can indicate the relative priority of streams. An implementation uses information provided by the application to determine how to allocate resources to active streams.

Also we should try using strategy pattern, so that client can pass it's own priority algorithm as a parameter.

Possible Solution I want to implement:

As standard solution suggests, we can use Priority Parameters in HTTP Headers like

priority = u=, I
Where u is urgence(int), and i(boolean) is incremental processing for signaling request priority to origins (and intermediaries).

and for Reprioritization we can use PRIORITY_UPDATE frames.

Questions in which I need help:

1. For Reprioritization using PRIORITY_UPDATE do we have any control streams as mentioned here ?

PRIORITY_UPDATE frames are sent by clients on the control stream, allowing them to be sent independently of the stream that carries the response. This means they can be used to reprioritize a response or a push stream, or to signal the initial priority of a response instead of the Priority header field

2. Do we have any registry in quic-go (which can live on server, even if connection is closed) needed for implementing 4.3.1 Registration
3. Why do we need streamQueue in framer.go ?
4. Since quic-go is maintaining 4 maps in stream_maps.go do we need to prioritize streams among outgoingBidiStreams, outgoingUniStreams, incomingBidiStreams, incomingUniStreams
5. in streams_map.go why do we need perspective protocol.Perspective when we are assigning StreamID based on Server and Client ?
6. Please add any further detail which you think a new comer should know before starting to implement this feature.

[marten-seemann]

CloudFlare just published a blog post: https://blog.cloudflare.com/better-http-3-prioritization-for-a-faster-web/

[tobbee]

I'm interested in having priorities in QUIC stream for MOQ Transport via the moqtransport project, but it would of course be nice to have an API that also works for H3. For MOQ, priorities are quite essential, starting with a control channel that should always have highest priority.

As references, I've looked at moxygen+mvfst for MOQ + QUIC case for MOQ priorities, and quiche for H3 + RFC 9218. I've also looked at other implementation and finally used Claude Code with Opus 4 to analyze the different projects and come up with a plan for implementing this with a proper API in multiple steps. Below is the architecture description.

I'm personally more interested in the MOQ part, but I hope this looks promising also for H3 and RFC 9218.

@marten-seemann What are your thoughts on this?

quic-go Priority Architecture Diagrams

Overall Architecture

┌────────────────────────────────────────────────────────────────┐
│                        Application Layer                       │
│                                                                │
│  ┌─────────────────┐  ┌──────────────────┐  ┌───────────────┐  │
│  │  HTTP/3 Server  │  │  MOQ Application │  │ Custom Proto  │  │
│  │                 │  │                  │  │               │  │
│  │ Priority: u=2,i │  │ subPri=10        │  │ priority=high │  │
│  └────────┬────────┘  └────────┬─────────┘  └───────┬───────┘  │
│           │                    │                    │          │
└───────────┼────────────────────┼────────────────────┼───────-──┘
            │                    │                    │
            ▼                    ▼                    ▼
┌────────────────────────────────────────────────────────────────┐
│                      Priority API Layer                        │
│                                                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  stream.SetPriority(urgency, incremental)               │   │
│  │  stream.GetPriority() → Priority{Urgency: 2, Incr: true}│   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                │
│  ┌──────────────┐  ┌──────────────────┐  ┌────────────────┐    │
│  │ RFC9218      │  │ MOQPriority      │  │ CustomPriority │    │
│  │ Scheme       │  │ Scheme           │  │ Scheme         │    │
│  └──────────────┘  └──────────────────┘  └────────────────┘    │
└────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌────────────────────────────────────────────────────────────────┐
│                    Priority Scheduler                          │
│                                                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Urgency Level 0 (Highest)             │   │
│  │  ┌─────────────────┐        ┌─────────────────────┐     │   │
│  │  │ Sequential Heap │        │ Round-Robin Queue   │     │   │
│  │  │ [S1, S3, S7]    │        │ [S2]→[S4]→[S6]→⟲    │     │   │
│  │  └─────────────────┘        └─────────────────────┘     │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Urgency Level 1                       │   │
│  │  ┌─────────────────┐        ┌─────────────────────┐     │   │
│  │  │ Sequential Heap │        │ Round-Robin Queue   │     │   │
│  │  │ [S8, S11]       │        │ [S9]→[S10]→[S12]→⟲  │     │   │
│  │  └─────────────────┘        └─────────────────────┘     │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                │
│                    ... Urgency Levels 2-7 ...                  │
└────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌────────────────────────────────────────────────────────────────┐
│                      QUIC Transport Layer                      │
│                                                                │
│  ┌─────────────────┐  ┌──────────────────┐  ┌──────────────┐   │
│  │ Packet Packer   │  │ Flow Controller  │  │ Congestion   │   │
│  │                 │  │                  │  │ Controller   │   │
│  │ GetNextStream() │  │ SendWindow: 64KB │  │ CWND: 10pkts │   │
│  └─────────────────┘  └──────────────────┘  └──────────────┘   │
└────────────────────────────────────────────────────────────────┘

Priority Scheduler Detail

Priority Scheduler
├── getNextStream()
│   │
│   ├── [Urgency 0] ─── Check Sequential? ─── YES ──→ Return Stream
│   │                           │
│   │                          NO
│   │                           ▼
│   │                   Check Round-Robin? ─── YES ──→ Return Stream
│   │                           │
│   │                          NO
│   │                           ▼
│   ├── [Urgency 1] ─── Check Sequential? ─── YES ──→ Return Stream
│   │                           │
│   │                          NO
│   │                           ▼
│   │                   Check Round-Robin? ─── YES ──→ Return Stream
│   │                           │
│   │                          NO
│   │                           ▼
│   └── ... Continue through Urgency 7 ...
│
└── No streams with data → return nil

Sequential vs Incremental Scheduling

Sequential (Non-Incremental) Streams

Urgency 2 Sequential Heap:

         ┌─────┐
         │ S15 │  ← Top (highest priority)
         └──┬──┘
        ╱       ╲
    ┌──┴──┐   ┌──┴──┐
    │ S17 │   │ S23 │
    └─────┘   └─────┘

Scheduling: Always take S15 until it has no more data,
            then S17, then S23 (strict priority order)

Incremental (Round-Robin) Streams

Urgency 2 Round-Robin Queue:

    ┌────┐     ┌────┐     ┌────┐     ┌────┐
 →  │S16 │ ──→ │S18 │ ──→ │S20 │ ──→ │S22 │ ↓
    └────┘     └────┘     └────┘     └────┘ │
       ↑                                    │
       └────────────────────────────────────┘
                    current ↓

Scheduling: S16 → S18 → S20 → S22 → S16 → ... (fair sharing)
            Each gets equal opportunity regardless of data amount

MOQ Priority Encoding Example

MOQ Priority Encoding (64 bits):

┌────────┬──────────────┬──────────────┬─────────────────────┬─────────────────────┐
│ 6 bits │   8 bits     │   8 bits     │      21 bits        │      21 bits        │
├────────┼──────────────┼──────────────┼─────────────────────┼─────────────────────┤
│Reserved│ Subscriber   │ Publisher    │    Group ID         │    Object ID        │
│ (0)    │ Priority     │ Priority     │    (truncated)      │    (truncated)      │
└────────┴──────────────┴──────────────┴─────────────────────┴─────────────────────┘

Example Values:
- Control Stream:  0x0000000000000000 (all zeros = highest priority)
- Audio Stream:    0x0A0500000001A000 (subPri=10, pubPri=5, group=1, obj=0xA000)
- Video Stream:    0x140A00000002B000 (subPri=20, pubPri=10, group=2, obj=0xB000)

Comparison: Control > Audio > Video (lower value = higher priority)

HTTP/3 Priority Flow

Client                          Server
  │                               │
  ├──── HTTP Request ────────────→│
  │     Headers:                  │
  │     :path: /video.mp4         │
  │     priority: u=2, i          │
  │                               │
  │                               ├── Parse Priority Header
  │                               ├── stream.SetPriority(2, true)
  │                               │
  │←──── HTTP Response ───────────┤
  │     Stream scheduled with     │
  │     urgency=2, incremental    │
  │                               │
  ├──── PRIORITY_UPDATE ─────────→│
  │     Stream: 4                 │
  │     Priority: u=1             ├── Update Stream Priority
  │                               ├── stream.SetPriority(1, false)
  │                               │
  │←──── Rescheduled Data ────────┤
  │     Now with urgency=1        │
  │                               │

Memory Layout

StreamMeta Structure (64 bytes aligned):
┌─────────────────────┬────────┬─────────┐
│ StreamID (8)        │Priority│ Padding │
├─────────────────────┼────────┼─────────┤
│ HasData func (8)    │BytesPending func │
├─────────────────────┴──────────────────┤
│ LastServiced time.Time (16)            │
├────────────────────────────────────────┤
│ BytesServed (8)     │ HeapIndex (4)│pad│
├─────────────────────┴────────────-─┴───┤
│ QueueNode pointer (8)                  │
└────────────────────────────────────────┘

Optimized for cache line efficiency (64-byte boundary)

Performance Characteristics

Operation Complexity:

├── AddStream         O(log n) for sequential, O(1) for incremental
├── RemoveStream      O(log n) for sequential, O(1) for incremental
├── UpdatePriority    O(log n) + remove + add
├── GetNextStream     O(1) best case, O(log n) worst case
└── RoundRobinAdvance O(1)

Memory Usage:
- Per stream: ~64 bytes metadata
- Per urgency level: 2 pointers (heap + round-robin)
- Total overhead: ~512 bytes + (64 * num_streams)

Cache Behavior:
- Hot path (GetNextStream) touches minimal memory
- Sequential heap benefits from cache locality
- Round-robin queue uses circular buffer for cache efficiency

Integration Points

Modified Files:
quic-go/
├── config.go              (+10 lines: priority config)
├── connection.go          (+20 lines: scheduler init)
├── send_stream.go         (+30 lines: priority methods)
├── streams_map.go         (+15 lines: scheduler integration)
├── packet_packer.go       (+25 lines: priority scheduling)
│
├── internal/
│   └── priority/          (NEW: ~1500 lines)
│       ├── scheduler.go
│       ├── queue.go
│       ├── heap.go
│       └── round_robin.go
│
└── http3/
    ├── frames.go          (+50 lines: PRIORITY_UPDATE)
    ├── priority.go        (NEW: ~300 lines)
    └── server.go          (+40 lines: priority handling)

Total: ~2000 lines of new code, ~140 lines of modifications

• mvfst HTTPPriorityQueue: Reference implementation
• moxygen MOQ priorities: MOQ priority encoding
• quiche h3 priorities: Production RFC 9218 implementation