Skip to content

docs(quest): plan signed priority #4275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kixelated merged 2 commits into from
Sep 27, 2026
Merged

docs(quest): plan signed priority #4275

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1035572
docs(quest): plan signed priority
kixelated Sep 26, 2026
4b4b617
docs(quest): signed priority covers archive and concept docs
kixelated Sep 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions quest/m1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics.
- [BBR idle burst](/quest/m1/bbr-idle-burst.md) - a BBRv3 burst after a long idle paces near the learned bandwidth, proven by a fork regression
- [P2P](/quest/m1/p2p/README.md) - opted-in clients serve each other over data channels and iroh while the relay stays the rendezvous and the fallback, under application policy
- [One port](/quest/m1/one-port/README.md) - a relay speaks QUIC, STUN, WebRTC media, and SRT on one UDP port and HTTP, RTMP, and RTMPS on one TCP port
- [Signed priority](/quest/m1/signed-priority.md) - on dev, every API priority is an `i8` with 0 as the unset midpoint, and hang's built-ins sit above it
- [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, and a shared cluster session is fair across tenants
- [Stream sessions](/quest/m1/uring-tcp/README.md) - serve WebSocket and HTTP from the io_uring workers, where io_uring pays off most
- [IETF on the ring](/quest/m1/uring-ietf.md) - the io_uring workers serve moq-transport sessions too, so a uring relay drops no client protocol
Expand Down
44 changes: 44 additions & 0 deletions quest/m1/signed-priority.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# [L] Signed priority

## Goal

Every priority in the API is an `i8`, higher first, with 0 as the unset
midpoint: `track::Info`, `Subscription`, and `group::Fetch` in Rust, their
JS counterparts, moq-ffi, libmoq, and every wrapper. Nobody has to know that
127 is the middle of a `u8`, the default the moxygen line ships. The wire
stays a byte.
Comment on lines +5 to +9

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include the archived priority in the signed migration

The claim that every API priority becomes signed omits the exported moq_archive::Info::priority, which remains a u8 and is serialized into version-1 .info JSON. This would either leave a public priority API inconsistent or, if changed without planning, make existing values above 127 unreadable or alter their meaning. Add the archive API and a backward-compatible storage mapping or version migration to this quest.

AGENTS.md reference: quest/AGENTS.md:L74-L77

Useful? React with 馃憤聽/ 馃憥.

@kixelated kixelated Sep 27, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, added in 4b4b617: the archive priority joins the migration, keeping existing .info files meaningful.

(Written by Claude Opus 5.5)


## Plan

Decided with the maintainer:

- moq-lite carries `p + 128` (flip the top bit). The mapping is one-to-one
and keeps order, so a given byte means what it means today; only the API
number changes. The default becomes byte 128.
- IETF carries `128 - p`, saturating. An unset priority goes out as the
draft's usual 128, and an absent IETF priority decodes to 0. The cost is
that i8 -128 and -127 share byte 255, and IETF bytes 0 and 1 both decode to
127. Pin both ends in tests.
- hang's built-in priorities move above 0, so hang media outranks a track that
never set one. Something like catalog 40, text 30, audio 20, video 10; the
spacing is the implementer's call. Rust and JS keep matching values.
Comment on lines +22 to +24

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep every hang priority above the unset value

The proposed video 0 value contradicts the stated outcome that all hang media outranks an unset track, because the new unset priority is also 0. An implementation following this example would let default-priority traffic tie with video rather than remain below it, so choose a positive video value or narrow the stated ordering requirement.

AGENTS.md reference: quest/AGENTS.md:L35-L39

Useful? React with 馃憤聽/ 馃憥.

@kixelated kixelated Sep 27, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, the example video priority is now 10 in 4b4b617.

(Written by Claude Opus 5.5)

- A zeroed libmoq `moq_track_info` then means the default, which retires the
need for a `priority_present` flag.

Changing published `u8` fields to `i8` is an API break in every language, so
this lands on `dev`. Look for anything that does arithmetic on priority
(the lite send queue, JS send-order packing, the bandwidth allocator, the
relay's max-of-subscribers) and keep its ordering, not just its type.
Comment on lines +28 to +31

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add the required conceptual documentation updates

The implementation scope never includes the conceptual docs, although doc/concept/moq-lite.md still documents priorities as 0..255 and doc/concept/standard.md says IETF byte 128 maps to model priority 127. Both become false after this migration, so completing the quest as written would leave the published API semantics stale; include those updates in the plan.

AGENTS.md reference: AGENTS.md:L94-L98

Useful? React with 馃憤聽/ 馃憥.

@kixelated kixelated Sep 27, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, both concept docs are in scope as of 4b4b617.

(Written by Claude Opus 5.5)


moq-archive's `Info::priority` follows. Its version-1 `.info` stores the
`u8`, so existing recordings must keep their meaning: store the moq-lite byte
(`p + 128`) or bump the format version, never reinterpret silently.
`doc/concept/moq-lite.md` (the 0..255 knob) and `doc/concept/standard.md`
(IETF 128 maps to 127) move to the new range and mapping.

Report the wire impact in the PR: none in format, but the default byte on
moq-lite moves again.

## Related

- [Scope track priority](/quest/m1/track-priority-scope.md) - which streams a priority competes with, not its type
Loading