feat!: signed track priorities with a publisher tiebreak

cpp/moq/MIGRATE.md

@@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.
 
 ## Unreleased
 
+### Priorities are signed (#6142)
+
+`TrackInfo::priority`, `Subscription::priority`, and `FetchGroupOptions::priority` are `int8_t`, and `GroupRequest::priority()` returns one.
+Higher is first and 0 is the unset midpoint; `TrackInfo::priority` defaulted to 127 and now defaults to 0.
+To keep a value's moq-lite byte, subtract 128 from it, widening first (`static_cast<int8_t>(int(old) - 128)`): 255 becomes 127, 128 becomes 0, and 0 becomes -128.
+
 ### A client asks only about what it watches (#6165)
 
 On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced` or `announced_broadcast`, instead of under its whole scope at connect.

dart/moq/MIGRATE.md

@@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.
 
 ## Unreleased
 
+### Priorities are signed (#6142)
+
+`TrackInfo.priority`, `Subscription.priority`, and `FetchGroupOptions.priority` take `-128..=127`, higher first, and 0 is the unset midpoint.
+`TrackInfo.priority` defaulted to 127 and now defaults to 0.
+To keep a value's moq-lite byte, subtract 128 from it: 255 becomes 127, 128 becomes 0, and 0 becomes -128.
+
 ### A client asks only about what it watches (#6165)
 
 On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect.

dart/moq_ffi/MIGRATE.md

@@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first.
 
 ## Unreleased
 
+### Priorities are signed (#6142)
+
+`MoqTrackInfo.priority`, `MoqSubscription.priority`, `MoqFetchGroupOptions.priority`, and `MoqGroupRequest.priority()` take `-128..=127`, higher first, and 0 is the unset midpoint.
+`MoqTrackInfo.priority` defaulted to 127 and now defaults to 0.
+To keep a value's moq-lite byte, subtract 128 from it: 255 becomes 127, 128 becomes 0, and 0 becomes -128.
+Regenerate the bindings for the changed checksums.
+
 ### A client asks only about what it watches (#6165)
 
 On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect.

dart/moq_ffi/lib/src/moq.dart

@@ -579,7 +579,7 @@ class FfiConverterMoqFetchGroupOptions {
 
   static LiftRetVal<MoqFetchGroupOptions> read(Uint8List buf) {
     int new_offset = buf.offsetInBytes;
-    final priority_lifted = FfiConverterUInt8.read(
+    final priority_lifted = FfiConverterInt8.read(
       Uint8List.view(buf.buffer, new_offset),
     );
     final priority = priority_lifted.value;
@@ -597,7 +597,7 @@ class FfiConverterMoqFetchGroupOptions {
 
   static RustBuffer lower(MoqFetchGroupOptions value) {
     final total_length =
-        FfiConverterUInt8.allocationSize(value.priority) +
+        FfiConverterInt8.allocationSize(value.priority) +
         FfiConverterOptionalUInt64.allocationSize(value.maxDelayUs) +
         0;
     final buf = Uint8List(total_length);
@@ -607,7 +607,7 @@ class FfiConverterMoqFetchGroupOptions {
 
   static int write(MoqFetchGroupOptions value, Uint8List buf) {
     int new_offset = buf.offsetInBytes;
-    new_offset += FfiConverterUInt8.write(
+    new_offset += FfiConverterInt8.write(
       value.priority,
       Uint8List.view(buf.buffer, new_offset),
     );
@@ -619,7 +619,7 @@ class FfiConverterMoqFetchGroupOptions {
   }
 
   static int allocationSize(MoqFetchGroupOptions value) {
-    return FfiConverterUInt8.allocationSize(value.priority) +
+    return FfiConverterInt8.allocationSize(value.priority) +
         FfiConverterOptionalUInt64.allocationSize(value.maxDelayUs) +
         0;
   }
@@ -704,7 +704,7 @@ class FfiConverterMoqSubscription {
 
   static LiftRetVal<MoqSubscription> read(Uint8List buf) {
     int new_offset = buf.offsetInBytes;
-    final priority_lifted = FfiConverterUInt8.read(
+    final priority_lifted = FfiConverterInt8.read(
       Uint8List.view(buf.buffer, new_offset),
     );
     final priority = priority_lifted.value;
@@ -737,7 +737,7 @@ class FfiConverterMoqSubscription {
 
   static RustBuffer lower(MoqSubscription value) {
     final total_length =
-        FfiConverterUInt8.allocationSize(value.priority) +
+        FfiConverterInt8.allocationSize(value.priority) +
         FfiConverterUInt64.allocationSize(value.maxDelayUs) +
         FfiConverterOptionalSequenceMoqRange.allocationSize(value.ranges) +
         FfiConverterOptionalMoqOrder.allocationSize(value.order) +
@@ -749,7 +749,7 @@ class FfiConverterMoqSubscription {
 
   static int write(MoqSubscription value, Uint8List buf) {
     int new_offset = buf.offsetInBytes;
-    new_offset += FfiConverterUInt8.write(
+    new_offset += FfiConverterInt8.write(
       value.priority,
       Uint8List.view(buf.buffer, new_offset),
     );
@@ -769,7 +769,7 @@ class FfiConverterMoqSubscription {
   }
 
   static int allocationSize(MoqSubscription value) {
-    return FfiConverterUInt8.allocationSize(value.priority) +
+    return FfiConverterInt8.allocationSize(value.priority) +
         FfiConverterUInt64.allocationSize(value.maxDelayUs) +
         FfiConverterOptionalSequenceMoqRange.allocationSize(value.ranges) +
         FfiConverterOptionalMoqOrder.allocationSize(value.order) +
@@ -2739,7 +2739,7 @@ class MoqTrackInfo {
   final int? timescale;
   final bool compress;
   MoqTrackInfo({
-    this.priority = 127,
+    this.priority = 0,
     this.maxAgeUs = null,
     this.refresh = null,
     this.timescale = null,
@@ -2754,7 +2754,7 @@ class FfiConverterMoqTrackInfo {
 
   static LiftRetVal<MoqTrackInfo> read(Uint8List buf) {
     int new_offset = buf.offsetInBytes;
-    final priority_lifted = FfiConverterUInt8.read(
+    final priority_lifted = FfiConverterInt8.read(
       Uint8List.view(buf.buffer, new_offset),
     );
     final priority = priority_lifted.value;
@@ -2793,7 +2793,7 @@ class FfiConverterMoqTrackInfo {
 
   static RustBuffer lower(MoqTrackInfo value) {
     final total_length =
-        FfiConverterUInt8.allocationSize(value.priority) +
+        FfiConverterInt8.allocationSize(value.priority) +
         FfiConverterOptionalUInt64.allocationSize(value.maxAgeUs) +
         FfiConverterOptionalUInt32.allocationSize(value.refresh) +
         FfiConverterOptionalUInt64.allocationSize(value.timescale) +
@@ -2806,7 +2806,7 @@ class FfiConverterMoqTrackInfo {
 
   static int write(MoqTrackInfo value, Uint8List buf) {
     int new_offset = buf.offsetInBytes;
-    new_offset += FfiConverterUInt8.write(
+    new_offset += FfiConverterInt8.write(
       value.priority,
       Uint8List.view(buf.buffer, new_offset),
     );
@@ -2830,7 +2830,7 @@ class FfiConverterMoqTrackInfo {
   }
 
   static int allocationSize(MoqTrackInfo value) {
-    return FfiConverterUInt8.allocationSize(value.priority) +
+    return FfiConverterInt8.allocationSize(value.priority) +
         FfiConverterOptionalUInt64.allocationSize(value.maxAgeUs) +
         FfiConverterOptionalUInt32.allocationSize(value.refresh) +
         FfiConverterOptionalUInt64.allocationSize(value.timescale) +
@@ -11764,7 +11764,7 @@ class MoqGroupRequest implements MoqGroupRequestInterface {
         uniffiClonePointer(),
         status,
       ),
-      FfiConverterUInt8.lift,
+      FfiConverterInt8.lift,
       null,
     );
   }
@@ -13340,6 +13340,29 @@ class FfiConverterDouble64 {
   }
 }
 
+class FfiConverterInt8 {
+  static int lift(int value) => value;
+  static LiftRetVal<int> read(Uint8List buf) {
+    return LiftRetVal(buf.buffer.asByteData(buf.offsetInBytes).getInt8(0), 1);
+  }
+
+  static int lower(int value) {
+    if (value < -128 || value > 127) {
+      throw ArgumentError("Value out of range for i8: " + value.toString());
+    }
+    return value;
+  }
+
+  static int allocationSize([int value = 0]) {
+    return 1;
+  }
+
+  static int write(int value, Uint8List buf) {
+    buf.buffer.asByteData(buf.offsetInBytes).setInt8(0, lower(value));
+    return 1;
+  }
+}
+
 class FfiConverterMapStringToMoqAudio {
   static Map<String, MoqAudio> lift(RustBuffer buf) {
     return FfiConverterMapStringToMoqAudio.read(buf.asUint8List()).value;
@@ -15515,29 +15538,6 @@ class FfiConverterUInt64 {
   }
 }
 
-class FfiConverterUInt8 {
-  static int lift(int value) => value;
-  static LiftRetVal<int> read(Uint8List buf) {
-    return LiftRetVal(buf.buffer.asByteData(buf.offsetInBytes).getUint8(0), 1);
-  }
-
-  static int lower(int value) {
-    if (value < 0 || value > 255) {
-      throw ArgumentError("Value out of range for u8: " + value.toString());
-    }
-    return value;
-  }
-
-  static int allocationSize([int value = 0]) {
-    return 1;
-  }
-
-  static int write(int value, Uint8List buf) {
-    buf.buffer.asByteData(buf.offsetInBytes).setUint8(0, lower(value));
-    return 1;
-  }
-}
-
 class FfiConverterUint8List {
   static Uint8List lift(RustBuffer value) {
     return FfiConverterUint8List.read(value.asUint8List()).value;
@@ -17491,7 +17491,7 @@ external Pointer<Void> uniffi_moq_ffi_fn_method_moqgrouprequest_demand(
   Pointer<RustCallStatus> uniffiStatus,
 );
 
-@Native<Uint8 Function(Pointer<Void>, Pointer<RustCallStatus>)>(
+@Native<Int8 Function(Pointer<Void>, Pointer<RustCallStatus>)>(
   assetId: _uniffiAssetId,
 )
 external int uniffi_moq_ffi_fn_method_moqgrouprequest_priority(
@@ -19692,7 +19692,7 @@ void _checkApiChecksums() {
   if (uniffi_moq_ffi_checksum_method_moqgrouprequest_demand() != 31288) {
     throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
   }
-  if (uniffi_moq_ffi_checksum_method_moqgrouprequest_priority() != 1745) {
+  if (uniffi_moq_ffi_checksum_method_moqgrouprequest_priority() != 15373) {
     throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
   }
   if (uniffi_moq_ffi_checksum_method_moqgrouprequest_sequence() != 29523) {

doc/concept/moq-lite.md

@@ -236,7 +236,7 @@ Each subscription carries the knobs that decide behavior under congestion:
 
 | Knob | Effect |
 | --- | --- |
-| **Priority** (0..255) | Higher-priority tracks get bandwidth first. Audio above video, base layer above enhancement. From a native Rust publisher over QUIC or WebTransport (iroh excepted), subscriptions at the same priority split bandwidth evenly by bytes, streams and datagrams alike, however many groups each has queued. A browser publisher and other transports without send groups are not covered. |
+| **Priority** (-128..127, default 0) | Higher-priority tracks get bandwidth first. Audio above video, base layer above enhancement. The publisher's track priority breaks ties between subscriptions at one priority. From a native Rust publisher over QUIC or WebTransport (iroh excepted), subscriptions at the same priority and publisher priority split bandwidth evenly by bytes, streams and datagrams alike, however many groups each has queued. A browser publisher and other transports without send groups are not covered. |
 | **Order** | Which group to send first when several are pending. Newest first for live (the default), oldest first for catch-up. Needs moq-lite 07 or moq-transport; older moq-lite always sends newest first. |
 | **Max delay** | How long a non-latest group stays worth delivering before it is skipped. Zero means "live edge only", and raising it is also what asks for history. |
 | **Ranges** | Which groups to ask for: from a group, a number of groups back from the latest, or the group containing a presentation time, optionally up to an end. The default asks for everything max delay allows. Max delay still caps every range. |

doc/concept/standard.md

@@ -35,7 +35,7 @@ subset drops. What a peer actually observes against this implementation:
 - **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0` on a `SUBSCRIBE`, JavaScript's `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority, negotiated subscriber max age, and delivery timeouts; Rust also renews request tokens and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix.
 - **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0, including across a moq-lite-07 hop between two relays that negotiate the [ietf](/draft/moq-ietf) extension. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. On a timed track the frame holds each object's time, so a mutable Timestamp that only repeats the immutable one is not restated; a status object has no frame, so it keeps its Timestamp among its properties. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects.
 - **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. A moq-lite-07 hop (`moq-lite-07-wip`, opt-in) carries the same demand natively: the ratio in `TRACK_INFO` and the asked-for group in `SUBSCRIBE_UPDATE`. Earlier moq-lite versions carry neither, so a track received over one never refreshes.
-- **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it.
+- **Priority.** Higher is served first. This stack's priorities run from -128 to 127 with 0 unset, and go out on the IETF wire, which ranks lower first, as `127 - priority`: an unset priority is IETF 127, and an absent IETF priority is 0. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it.
 - **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's.
 
 Several project drafts extend the IETF wire without breaking it, since `SETUP`

doc/setup/upgrade.md

@@ -32,6 +32,14 @@ ignored; its guide says what replaces it.
 
 These land with the next breaking release.
 
+- **The default priority byte moves again.** Priorities are signed in every
+  API, -128 to 127 with 0 unset, so nobody has to know that 127 is the middle
+  of a byte. The wire keeps one byte and one urgency on both protocols, so an
+  unset priority now goes out as 128 on moq-lite (was 127) and 127 on
+  moq-transport (was 128); the previous release moved it to match moxygen.
+  hang's media priorities now sit above that default rather than below it.
+  Mixed versions only differ in how an unset priority ranks against a set one,
+  so upgrade publishers and players in either order.
 - **WebSocket needs a QMux subprotocol** (#6231). Relays answer a WebSocket
   upgrade that offers no `qmux-NN` subprotocol with 400 instead of falling back
   to the legacy `webtransport` format, so upgrade such clients before relays.

drafts/draft-lcurley-moq-hang.md

@@ -992,7 +992,7 @@ The `store` field, if present, is the object-store URL the recording objects liv
 Authorization for `replay` and `store` is external.
 
 The `version` field is the version of that recording object format.
-It is 2 for this specification.
+It is 3 for this specification.
 A publisher that exposes a store MUST set it; a publisher that does not MUST omit it.
 
 A catalog that composes another broadcast's renditions MUST preserve that child's `archive` entry instead of synthesizing one.
@@ -1189,6 +1189,7 @@ This document has no IANA actions.
 ## moq-hang-04
 {:numbered="false"}
 
+- The archive `version` is 3: the recording format stores a track's `priority` signed, -128 through 127 with 0 unset, instead of its moq-lite byte.
 - A reader refuses a JSON frame in which an object repeats a member name.
 - Added the root `version` ({{catalog-version}}): the oldest draft that reads the catalog, which a consumer refuses when above its own. A `track` other than the entry's ID or a video `warmup` needs 4. Consumers MUST ignore unknown fields.
 - A data track marks a discontinuity with a group of one object with no bytes, since its empty payload is data. An object with no bytes on an audio or video track, or sharing its group, is malformed.