Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
988ac2d
quest: claim m1/refresh/json
kixelated Oct 20, 2026
b37ccd9
feat(json)!: roll snapshot and window groups on joiner demand
kixelated Oct 20, 2026
1ec5cf2
feat(json)!: move in-repo callers to deltas/ops switches and refresh
kixelated Oct 20, 2026
86111bd
feat(ffi)!: replace delta_ratio with deltas and drive json snapshot r…
kixelated Oct 20, 2026
aafc85e
feat(json)!: replace deltaRatio/opRatio with deltas/ops and refresh o…
kixelated Oct 20, 2026
f2c7219
feat(bindings)!: replace delta_ratio with deltas across bindings, doc…
kixelated Oct 20, 2026
fa04496
Merge remote-tracking branch 'origin/main' into quest-m1-refresh-json
kixelated Oct 20, 2026
2dca98a
style: format refresh changes and fix the merged chat caller
kixelated Oct 20, 2026
db915ce
test(ffi): accept a joiner that skips straight to the refreshed group
kixelated Oct 20, 2026
9582c85
Merge origin/main into quest/m1/refresh/json
kixelated Oct 20, 2026
1c8adf3
test(json): cross real group boundaries in the compressed roundtrip
kixelated Oct 20, 2026
263f0c8
Merge remote-tracking branch 'origin/main' into merge-main-6054
kixelated Oct 20, 2026
407a717
Merge remote-tracking branch 'origin/main' into merge-main-6054
kixelated Oct 20, 2026
4dc084c
fix(json): restate at the newest timestamp written
kixelated Oct 20, 2026
cf88206
test(json): build the timestamp test's config in one expression
kixelated Oct 20, 2026
fc2f267
Merge origin/main into quest/m1/refresh/json
kixelated Oct 20, 2026
99d2ad6
Merge origin/main into quest/m1/refresh/json
kixelated Oct 21, 2026
19b1d15
fix(cli): roll report groups on joiner demand
kixelated Oct 21, 2026
4add172
Merge origin/main into quest/m1/refresh/json
kixelated Oct 21, 2026
1c43507
test(json): flush the demand signal with a microtask, not a timer
kixelated Oct 21, 2026
77699d5
Merge origin/main into quest/m1/refresh/json
kixelated Oct 21, 2026
7984f38
Merge origin/main into quest/m1/refresh/json
kixelated Oct 21, 2026
211d627
test(ffi): set compress on the refresh test's track info
kixelated Oct 21, 2026
2d27c40
Merge origin/main into quest/m1/refresh/json
kixelated Oct 21, 2026
6d54dfc
Merge origin/main into quest/m1/refresh/json
kixelated Oct 21, 2026
4221af6
Merge remote-tracking branch 'origin/main' into pr-6054
kixelated Oct 21, 2026
a0d6028
Merge remote-tracking branch 'origin/main' into merge-6054-b
kixelated Oct 21, 2026
13883d5
Merge remote-tracking branch 'origin/main' into merge/refresh-json-6054
kixelated Oct 22, 2026
c3c9cd3
docs(json): a refresh restates at the newest timestamp written
kixelated Oct 22, 2026
b58198e
Merge remote-tracking branch 'origin/main' into quest/m1/refresh/json
kixelated Oct 22, 2026
ed1deba
Merge remote-tracking branch 'origin/main' into quest/m1/refresh/json
kixelated Oct 22, 2026
5465196
fix(json): stage the snapshot baseline until the frame commits
kixelated Oct 22, 2026
52bba26
Merge origin/main into quest/m1/refresh/json
kixelated Oct 22, 2026
f66f48e
test(json): read the refreshed window event as Timed after the merge
kixelated Oct 22, 2026
31e220a
Merge origin/main into quest/m1/refresh/json
kixelated Oct 22, 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
6 changes: 6 additions & 0 deletions dart/moq/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.

## Unreleased

### JSON snapshot `deltaRatio` is `deltas`

`SnapshotConfig.deltaRatio` is replaced by `bool deltas` (default `true`).
Pass `deltas: false` where you passed `deltaRatio: 0`, and drop the argument otherwise.
Publish the track with a `refresh` ratio so a joiner gets the value restated in a fresh group.

### Priorities are signed (#6142)

`TrackInfo.priority`, `Subscription.priority`, and `FetchGroupOptions.priority` take `-128..=127`, higher first, and 0 is the unset midpoint.
Expand Down
20 changes: 10 additions & 10 deletions dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -930,9 +930,9 @@ class FfiConverterMoqFlateConfig {
}

class MoqJsonSnapshotConfig {
final int deltaRatio;
final bool deltas;
final bool compression;
MoqJsonSnapshotConfig({this.deltaRatio = 8, this.compression = false});
MoqJsonSnapshotConfig({this.deltas = true, this.compression = false});
}

class FfiConverterMoqJsonSnapshotConfig {
Expand All @@ -942,25 +942,25 @@ class FfiConverterMoqJsonSnapshotConfig {

static LiftRetVal<MoqJsonSnapshotConfig> read(Uint8List buf) {
int new_offset = buf.offsetInBytes;
final deltaRatio_lifted = FfiConverterUInt32.read(
final deltas_lifted = FfiConverterBool.read(
Uint8List.view(buf.buffer, new_offset),
);
final deltaRatio = deltaRatio_lifted.value;
new_offset += deltaRatio_lifted.bytesRead;
final deltas = deltas_lifted.value;
new_offset += deltas_lifted.bytesRead;
final compression_lifted = FfiConverterBool.read(
Uint8List.view(buf.buffer, new_offset),
);
final compression = compression_lifted.value;
new_offset += compression_lifted.bytesRead;
return LiftRetVal(
MoqJsonSnapshotConfig(deltaRatio: deltaRatio, compression: compression),
MoqJsonSnapshotConfig(deltas: deltas, compression: compression),
new_offset - buf.offsetInBytes,
);
}

static RustBuffer lower(MoqJsonSnapshotConfig value) {
final total_length =
FfiConverterUInt32.allocationSize(value.deltaRatio) +
FfiConverterBool.allocationSize(value.deltas) +
FfiConverterBool.allocationSize(value.compression) +
0;
final buf = Uint8List(total_length);
Expand All @@ -970,8 +970,8 @@ class FfiConverterMoqJsonSnapshotConfig {

static int write(MoqJsonSnapshotConfig value, Uint8List buf) {
int new_offset = buf.offsetInBytes;
new_offset += FfiConverterUInt32.write(
value.deltaRatio,
new_offset += FfiConverterBool.write(
value.deltas,
Uint8List.view(buf.buffer, new_offset),
);
new_offset += FfiConverterBool.write(
Expand All @@ -982,7 +982,7 @@ class FfiConverterMoqJsonSnapshotConfig {
}

static int allocationSize(MoqJsonSnapshotConfig value) {
return FfiConverterUInt32.allocationSize(value.deltaRatio) +
return FfiConverterBool.allocationSize(value.deltas) +
FfiConverterBool.allocationSize(value.compression) +
0;
}
Expand Down
4 changes: 2 additions & 2 deletions doc/lib/js/json.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ are the catalog modes on the [hang](/concept/hang#data-tracks) page. Window is
a third framing for a raw track: both ends opt into it, and a generic catalog
reader will not pick it up.

- **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error. `next()` yields every state in order; `latest()` skips to the newest.
- **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error. `next()` yields every state in order; `latest()` skips to the newest. Deltas ride one group until a joiner wants a fresh one: give the track a `refresh` ratio (8 is typical) and the producer restates the value in a new group. Without a ratio a group rolls only at its caps.
- **Stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log.
- **Window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice.
- **Window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. Its ops roll on the track's `refresh` ratio the same way.

Both sides choose the same compression, `"none"` or `"deflate"`. Producers take
a `Timed` value, `{ value, at }`, where `at` is the capture time written as
Expand Down
4 changes: 2 additions & 2 deletions doc/lib/rs/moq-json.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ stream are the catalog modes on the [hang](/concept/hang#data-tracks) page.
Window is a third framing for a raw track: both ends opt into it, and a
generic catalog reader will not pick it up.

- **snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. An unchanged update publishes nothing. Several owners can edit their own keys in place instead of clobbering one document.
- **snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. An unchanged update publishes nothing. Several owners can edit their own keys in place instead of clobbering one document. Deltas ride one group until a joiner wants a fresh one: set the track's `refresh` ratio (8 is typical) and drive `Producer::refresh`, which restates the value in a new group. Without a ratio a group rolls only at its caps.
- **stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log.
- **window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice.
- **window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. Its ops roll on the track's `refresh` ratio the same way.

Both sides choose the same compression. A bare value stays untimed; publish
`moq_net::Timed::from(&value).at(captured)` to retain a capture timestamp.
Expand Down
6 changes: 6 additions & 0 deletions go/wrapper/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.

## Unreleased

### JSON snapshot `DeltaRatio` is `Deltas`

`json.SnapshotOptions.DeltaRatio *uint32` and `json.DefaultDeltaRatio` are replaced by `Deltas *bool` (nil enables deltas).
Set `Deltas` to a pointer to `false` where you set `DeltaRatio` to a pointer to `0`, and leave it nil otherwise.
Publish the track with a `Refresh` ratio so a joiner gets the value restated in a fresh group.

### Priorities are signed (#6142)

`TrackInfo.Priority`, `Subscription.Priority`, and `FetchGroupOptions.Priority` are `int8`, and `GroupRequest.Priority()` returns one.
Expand Down
28 changes: 12 additions & 16 deletions go/wrapper/json/json.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,26 +20,22 @@ import (
"moq.dev/moq/internal/bridge"
)

// DefaultDeltaRatio is used when [SnapshotOptions.DeltaRatio] is nil. Go has no field
// defaults, so unlike the other bindings this restates the `#[uniffi(default = 8)]` on
// moq-ffi's MoqJsonSnapshotConfig (itself pinned to moq-json's default by a Rust test).
const DefaultDeltaRatio uint32 = 8

// SnapshotOptions configures a lossy latest-value JSON producer.
type SnapshotOptions struct {
// DeltaRatio controls how aggressively deltas replace full snapshots. Nil uses
// [DefaultDeltaRatio]; a pointer to zero disables deltas entirely.
DeltaRatio *uint32
// Deltas encodes updates as merge-patch deltas against the group's snapshot. Nil
// enables them, matching the other bindings; a pointer to false publishes every
// update as a full snapshot in its own group. With deltas on, give the track a
// refresh ratio so a joiner past it gets the value restated in a fresh group.
Deltas *bool
// Compression enables group-scoped DEFLATE and must match on the consumer.
Compression bool
}

// deltaRatio resolves the configured ratio, falling back to the shared default.
func (o SnapshotOptions) deltaRatio() uint32 {
if o.DeltaRatio == nil {
return DefaultDeltaRatio
}
return *o.DeltaRatio
// deltas resolves the configured switch. Go has no field defaults, so this restates the
// `#[uniffi(default = true)]` on moq-ffi's MoqJsonSnapshotConfig (itself pinned to
// moq-json's default by a Rust test).
func (o SnapshotOptions) deltas() bool {
return o.Deltas == nil || *o.Deltas
}

// StreamOptions configures a lossless append-log JSON producer.
Expand Down Expand Up @@ -69,7 +65,7 @@ func NewSnapshotProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProdu
inner, err := ffi.NewMoqJsonSnapshotProducer(
bridge.BroadcastProducer(broadcast),
bridge.TrackProducer(track),
ffi.MoqJsonSnapshotConfig{DeltaRatio: options.deltaRatio(), Compression: options.Compression},
ffi.MoqJsonSnapshotConfig{Deltas: options.deltas(), Compression: options.Compression},
)
if err != nil {
return nil, err
Expand Down Expand Up @@ -182,7 +178,7 @@ type SnapshotConsumer struct {
// NewSnapshotConsumer reads track as a lossy latest-value JSON track. It takes over
// track, whose handle is closed afterward, and fails if track has already read a group.
func NewSnapshotConsumer(track *moq.TrackConsumer, options ConsumerOptions) (*SnapshotConsumer, error) {
// DeltaRatio is producer-only; the consumer ignores it.
// Deltas is producer-only; the consumer ignores it.
inner, err := ffi.NewMoqJsonSnapshotConsumer(
bridge.TrackConsumer(track),
ffi.MoqJsonSnapshotConfig{Compression: options.Compression},
Expand Down
10 changes: 5 additions & 5 deletions js/hang/src/catalog/consumer.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ test("the shared containment check covers every section carrying a broadcast ref
test("watch refuses an oversized catalog update", async () => {
const broadcast = new Moq.Broadcast.Producer();
const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Root>({ track, deltaRatio: 0 });
const producer = new Json.Snapshot.Producer<Root>({ track, deltas: false });
const consumer = watch(broadcast.consume())[Symbol.asyncIterator]();
producer.update({ value: catalog(MAX_RENDITIONS + 1), at: Moq.Time.Timestamp.now() });
await expect(consumer.next()).rejects.toBeInstanceOf(TooManyRenditions);
Expand All @@ -71,7 +71,7 @@ test("watch refuses an oversized catalog update", async () => {
test("watch refuses a catalog needing a newer reader", async () => {
const broadcast = new Moq.Broadcast.Producer();
const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Root>({ track, deltaRatio: 0 });
const producer = new Json.Snapshot.Producer<Root>({ track, deltas: false });
const consumer = watch(broadcast.consume())[Symbol.asyncIterator]();
producer.update({ value: { version: VERSION + 1 }, at: Moq.Time.Timestamp.now() });
await expect(consumer.next()).rejects.toBeInstanceOf(UnsupportedVersion);
Expand All @@ -92,7 +92,7 @@ async function watchRequested(root: Root) {
const origin = new Moq.Origin.Producer();
const broadcast = origin.createBroadcast(Moq.Path.from("room/alice"));
const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Root>({ track, deltaRatio: 0 });
const producer = new Json.Snapshot.Producer<Root>({ track, deltas: false });
broadcast.announce();
const request = origin.request(Moq.Path.from("room/alice"));
const active = request.active.peek();
Expand Down Expand Up @@ -121,7 +121,7 @@ test("watch accepts a sibling reference under the same root and yields it unreso
test("watch on a standalone broadcast refuses any parent reference", async () => {
const broadcast = new Moq.Broadcast.Producer();
const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Root>({ track, deltaRatio: 0 });
const producer = new Json.Snapshot.Producer<Root>({ track, deltas: false });
const consumer = watch(broadcast.consume())[Symbol.asyncIterator]();
producer.update({ value: referencing("../bob"), at: Moq.Time.Timestamp.now() });
await expect(consumer.next()).rejects.toBeInstanceOf(EscapingBroadcast);
Expand All @@ -132,7 +132,7 @@ test("watch on a standalone broadcast refuses any parent reference", async () =>
test("watch subscribes and yields typed catalog updates", async () => {
const broadcast = new Moq.Broadcast.Producer();
const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Root>({ track, deltaRatio: 0 });
const producer = new Json.Snapshot.Producer<Root>({ track, deltas: false });
const consumer = watch(broadcast.consume())[Symbol.asyncIterator]();
producer.update({ value: catalog(1), at: Moq.Time.Timestamp.now() });
expect(await consumer.next()).toMatchObject({ value: catalog(1) });
Expand Down
10 changes: 10 additions & 0 deletions js/json/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,16 @@ How to update your code for each breaking change, newest first.

## Unreleased

### Groups roll on joiner demand

`Snapshot` `deltaRatio` and `Window` `opRatio` are replaced by `deltas` and `ops` booleans (both default `true`).
Pass `deltas: false` where you passed `deltaRatio: 0`, and `ops: false` where you passed `opRatio: 0`.
A group no longer rolls on a byte budget: create the track with a `refresh` ratio (`8` matches the old default), and the producer restates the value or window in a new group when a joiner asks.
Without a ratio a group rolls only at its frame and byte caps.
An `Encoder` user restates with `encoder.snapshot()` once `demand().wanted` passes the largest group it wrote.

`encoder.value` (and so `producer.mutate()`) now holds the last committed value: a rejected publish no longer carries into the next edit, so retry the edit yourself if you still want it.

### Duplicate keys are refused

Every decoder throws `DuplicateKey` for a frame in which a JSON object repeats a key, where `JSON.parse` used to keep the last copy.
Expand Down
2 changes: 1 addition & 1 deletion js/json/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ for await (const { value, at } of consumer) {
const current = await consumer.latest();
```

Pass `{ deltaRatio: x }` with a positive `x` to `Snapshot.Producer` to emit merge-patch deltas. A new snapshot group rolls once the deltas *already written* to the group exceed `x` times the fresh snapshot size; the delta that crosses the budget still lands first, so a group overshoots by at most one delta. `deltaRatio` defaults to `8` when unset. Set it to `0` to disable deltas: every change becomes a fresh single-frame snapshot group. Arrays are replaced wholesale within a delta; a value set to `null` falls back to a snapshot, since merge patch reads `null` as a key deletion.
Changes ride as merge-patch deltas by default; pass `{ deltas: false }` to make every change a fresh single-frame snapshot group. A group of deltas runs until a joiner wants a fresh one: give the track a `refresh` ratio (`track.accept({ refresh: 8 })`), and once the deltas outweigh that many snapshots a join asks for a new group, which the producer answers by restating the value at the newest timestamp written. Without a ratio a group rolls only at its frame or byte cap. Arrays are replaced wholesale within a delta; a value set to `null` falls back to a snapshot, since merge patch reads `null` as a key deletion.

### Stream: every record

Expand Down
2 changes: 1 addition & 1 deletion js/json/bench/codec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ for (const keys of [1, 10, 100, 1000]) {
for (const compression of ["none", "deflate"] as const) {
const samples: number[] = [];
for (let sample = 0; sample < 3; sample++) {
const config = { deltaRatio: 100, compression };
const config = { compression };
const encoder = new Encoder<Record<string, number>>(config);
const decoder = new Decoder<Record<string, number>>(config);
let value = Object.fromEntries(Array.from({ length: keys }, (_, n) => [`k${n}`, 0]));
Expand Down
Loading
Loading