Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 4 additions & 0 deletions doc/.vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,8 @@ export default defineConfig({
{ text: "moq-audio", link: "/lib/rs/moq-audio" },
{ text: "moq-auth", link: "/lib/rs/moq-auth" },
{ text: "moq-room", link: "/lib/rs/moq-room" },
{ text: "moq-json", link: "/lib/rs/moq-json" },
{ text: "moq-binary", link: "/lib/rs/moq-binary" },
],
},
{
Expand All @@ -180,6 +182,8 @@ export default defineConfig({
{ text: "@moq/room", link: "/lib/js/room" },
{ text: "@moq/auth", link: "/lib/js/auth" },
{ text: "@moq/signals", link: "/lib/js/signals" },
{ text: "@moq/json", link: "/lib/js/json" },
{ text: "@moq/binary", link: "/lib/js/binary" },
],
},
{ text: "Swift", link: "/lib/swift/" },
Expand Down
29 changes: 29 additions & 0 deletions doc/lib/js/binary.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
title: "@moq/binary"
description: Opaque binary payloads over MoQ tracks
---

# @moq/binary

[![npm](https://img.shields.io/npm/v/@moq/binary)](https://www.npmjs.com/package/@moq/binary)

Opaque payloads over [`@moq/net`](/lib/js/net) tracks, in two modes:

- **Snapshot**: lossy latest-value, one payload per group.
- **Stream**: lossless append-log in a single group.

The bytes are never inspected. Compression is [`@moq/flate`](https://www.npmjs.com/package/@moq/flate),
the same group-scoped DEFLATE `@moq/json` uses.

`Config` is the codec options. `Producer.Config` / `Consumer.Config` add the
track. Compression is a shared `"none" | "deflate"` enum, not a boolean: both
sides set the same field.

```ts
import { Snapshot } from "@moq/binary";

const producer = new Snapshot.Producer({ track, compression: "deflate" });
producer.update(payload);
```

The Rust twin is [`moq-binary`](/lib/rs/moq-binary).
3 changes: 2 additions & 1 deletion doc/lib/js/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ and WebAudio. `@moq/net` also runs in Node, Bun, and Deno.
| [@moq/room](/lib/js/room) | Headless rooms: announce-derived roster, local publish, remote watch, and a chat track. |
| [@moq/auth](/lib/js/auth) | Validate a relay's request, build its grant, and mint and verify relay JWTs. |
| [@moq/signals](/lib/js/signals) | The reactive primitives every package exposes its state through. |
| [@moq/json](https://www.npmjs.com/package/@moq/json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. |
| [@moq/json](/lib/js/json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. |
| [@moq/binary](/lib/js/binary) | Opaque payloads over tracks: snapshots or append logs. |
| [@moq/flate](https://www.npmjs.com/package/@moq/flate) | Group-scoped DEFLATE for any track. |
| [@moq/loc](https://www.npmjs.com/package/@moq/loc), [@moq/msf](https://www.npmjs.com/package/@moq/msf) | The IETF LOC container and MSF catalog. |
| [@moq/boy](https://www.npmjs.com/package/@moq/boy) | The [MoQ Boy](/bin/demo) player element. |
Expand Down
33 changes: 33 additions & 0 deletions doc/lib/js/json.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: "@moq/json"
description: JSON over MoQ tracks, as snapshots, streams, or a sliding window
---

# @moq/json

[![npm](https://img.shields.io/npm/v/@moq/json)](https://www.npmjs.com/package/@moq/json)

JSON over [`@moq/net`](/lib/js/net) tracks, in three modes:

- **Snapshot**: lossy latest-value, with RFC 7396 merge-patch deltas.
- **Stream**: lossless append-log in a single group.
- **Window**: a bounded run of records a reader can join at any point.

On Snapshot and Stream, `Config` is the codec options. `Producer.Config` /
`Consumer.Config` add the track. Compression is a shared `"none" | "deflate"`
enum, not a boolean: both sides set the same field. Window still uses
`ProducerConfig` / `ConsumerConfig` and a boolean `compression` flag.

```ts
import { Snapshot } from "@moq/json";

const producer = new Snapshot.Producer({ track, compression: "deflate" });
producer.update({ hello: "world" });

const consumer = new Snapshot.Consumer({ track: track.subscribe(), compression: "deflate" });
for await (const value of consumer) {
console.log(value);
}
```

The Rust twin is [`moq-json`](/lib/rs/moq-json).
3 changes: 2 additions & 1 deletion doc/lib/rs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ The reference implementation. Every crate is on
| [moq-transcode](https://docs.rs/moq-transcode) | Just-in-time rendition ladders, GPU-resident on NVIDIA. |
| [moq-auth](/lib/rs/moq-auth) | The authorization contract: requests, grants, leases, the HTTP client, the reference server, and JWT keys, signing, and verification. |
| [moq-room](/lib/rs/moq-room) | Headless rooms: announce-derived roster, token claims, and a chat track. |
| [moq-json](https://docs.rs/moq-json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. |
| [moq-json](/lib/rs/moq-json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. |
| [moq-binary](/lib/rs/moq-binary) | Opaque payloads over tracks: snapshots or append logs. |
| [moq-e2ee](https://docs.rs/moq-e2ee) | End-to-end encryption of groups, datagrams, catalogs, and track names. |
| [moq-flate](https://docs.rs/moq-flate) | Group-scoped DEFLATE for any track. |
| [moq-loc](https://docs.rs/moq-loc), [moq-msf](https://docs.rs/moq-msf) | The IETF LOC container and MSF catalog. |
Expand Down
32 changes: 32 additions & 0 deletions doc/lib/rs/moq-binary.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: moq-binary
description: Opaque binary payloads over MoQ tracks
---

# moq-binary

[![crates.io](https://img.shields.io/crates/v/moq-binary)](https://crates.io/crates/moq-binary)
[![docs.rs](https://docs.rs/moq-binary/badge.svg)](https://docs.rs/moq-binary)

Opaque payloads over [`moq-net`](/lib/rs/moq-net) tracks, in two modes:

- **snapshot**: lossy latest-value, one payload per group.
- **stream**: lossless append-log in a single group.

The bytes are never inspected. Compression is [`moq-flate`](https://docs.rs/moq-flate),
the same group-scoped DEFLATE `moq-json` uses.

`Config` is the codec options. The track-owning pair is `producer::Config` /
`consumer::Config`. Compression is a shared `Compression` enum (`None` or
`Deflate`), not a bool: both sides set the same field.

```rust
let mut config = moq_binary::snapshot::Config::default();
config.compression = moq_binary::Compression::Deflate;

let mut producer = moq_binary::snapshot::Producer::new(track, config);
producer.update(payload)?;
```

The TypeScript twin is [`@moq/binary`](/lib/js/binary). API:
[docs.rs/moq-binary](https://docs.rs/moq-binary).
32 changes: 32 additions & 0 deletions doc/lib/rs/moq-json.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: moq-json
description: JSON over MoQ tracks, as snapshots, streams, or a sliding window
---

# moq-json

[![crates.io](https://img.shields.io/crates/v/moq-json)](https://crates.io/crates/moq-json)
[![docs.rs](https://docs.rs/moq-json/badge.svg)](https://docs.rs/moq-json)

JSON over [`moq-net`](/lib/rs/moq-net) tracks, in three modes:

- **snapshot**: lossy latest-value, with RFC 7396 merge-patch deltas.
- **stream**: lossless append-log in a single group.
- **window**: a bounded run of records a reader can join at any point.

On snapshot and stream, `Config` is the codec options. The track-owning pair is
`producer::Config` / `consumer::Config`. Compression is a shared `Compression`
enum (`None` or `Deflate`), not a bool: both sides set the same field. Window
still uses `ProducerConfig` / `ConsumerConfig` and a boolean `compression`
flag.

```rust
let mut config = moq_json::snapshot::Config::default();
config.compression = moq_json::Compression::Deflate;

let mut producer = moq_json::snapshot::Producer::new(track, config);
producer.update(&value)?;
```

The TypeScript twin is [`@moq/json`](/lib/js/json). API:
[docs.rs/moq-json](https://docs.rs/moq-json).
6 changes: 4 additions & 2 deletions js/binary/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,7 @@ The bytes are opaque: this package frames them onto a track and optionally compr
never looks inside. For JSON documents reach for [`@moq/json`](../json) instead, which adds RFC 7396
merge-patch deltas on top of the same two modes.

Compression is [`@moq/flate`](../flate), the same group-scoped DEFLATE `@moq/json` uses, so the two
agree on the wire. Interoperable with the Rust `moq-binary` crate.
`Config` is the codec options (`compression: "none" | "deflate"`). `Producer.Config` /
`Consumer.Config` add the track. Compression is [`@moq/flate`](../flate), the same group-scoped
DEFLATE `@moq/json` uses, so the two agree on the wire. Interoperable with the Rust `moq-binary`
crate.
15 changes: 15 additions & 0 deletions js/binary/src/compression.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
/** How a binary track compresses its frames. `"none"` (the default) is uncompressed payloads. */
export type Compression = "none" | "deflate";

/** Whether `compression` is group-scoped DEFLATE. */
export function isDeflate(compression?: Compression): boolean {
switch (compression) {
case undefined:
case "none":
return false;
case "deflate":
return true;
default:
throw new Error(`unsupported compression: ${String(compression)}`);
}
}
1 change: 1 addition & 0 deletions js/binary/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,5 +24,6 @@
* @module
*/

export type { Compression } from "./compression.ts";
export * as Snapshot from "./snapshot/index.ts";
export * as Stream from "./stream/index.ts";
19 changes: 9 additions & 10 deletions js/binary/src/snapshot/consumer.ts
Original file line number Diff line number Diff line change
@@ -1,14 +1,8 @@
import { Decoder as Flate } from "@moq/flate";
import * as Moq from "@moq/net";

/** Snapshot consumer options, including the source track. */
export interface ConsumerConfig {
/** Track to read values from. */
track: Moq.Track.Subscriber;

/** Whether the frames are `deflate-raw` compressed. Must match the producer. Defaults to `false`. */
compression?: boolean;
}
import { isDeflate } from "../compression.ts";
import type { Config as CodecConfig } from "./producer.ts";

/**
* Consumes a binary value from a track, yielding the newest one.
Expand All @@ -27,9 +21,9 @@ export class Consumer {
// normally one frame, but the window is per group either way.
#flate?: Flate;

constructor(config: ConsumerConfig) {
constructor(config: Consumer.Config) {
this.#track = config.track.ordered();
this.#decompress = config.compression ?? false;
this.#decompress = isDeflate(config.compression);
}

/**
Expand Down Expand Up @@ -82,3 +76,8 @@ export class Consumer {
}
}
}

export namespace Consumer {
/** Snapshot consumer options, including the source track. */
export type Config = CodecConfig & { track: Moq.Track.Subscriber };
}
6 changes: 3 additions & 3 deletions js/binary/src/snapshot/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@
* preserved, use the `Stream` module instead.
*
* On the wire each value is one group holding one frame, so a group is self-contained and a
* consumer never needs an older one. With {@link ProducerConfig.compression} on, that frame is its
* consumer never needs an older one. With {@link Config.compression} `"deflate"`, that frame is its
* own raw DEFLATE stream; there is no window to share across a single-frame group.
*
* @module
*/

export { Consumer, type ConsumerConfig } from "./consumer.ts";
export { Producer, type ProducerConfig } from "./producer.ts";
export { Consumer } from "./consumer.ts";
export { type Config, Producer } from "./producer.ts";
24 changes: 15 additions & 9 deletions js/binary/src/snapshot/producer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,18 @@ import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate";
import * as Moq from "@moq/net";
import { Time } from "@moq/net";

/** Snapshot producer options, including the destination track. */
export interface ProducerConfig {
/** Track that receives each value as its own group. */
track: Moq.Track.Producer;
import { type Compression, isDeflate } from "../compression.ts";

/** Codec options for a snapshot track. */
export interface Config {
/**
* Compress each value as its own raw DEFLATE stream.
*
* A snapshot group holds a single self-contained value, so there is no window to share: each
* value is compressed alone. A {@link Consumer} reading the frames must set the same flag.
* Defaults to `false`.
* value is compressed alone. A {@link Consumer} reading the frames must set the same
* {@link compression}. Defaults to `"none"`.
*/
compression?: boolean;
compression?: Compression;
}

/**
Expand All @@ -29,9 +28,9 @@ export class Producer {
#compress: boolean;

/** Wrap a track to publish a binary value into it. */
constructor(config: ProducerConfig) {
constructor(config: Producer.Config) {
this.#track = config.track;
this.#compress = config.compression ?? false;
this.#compress = isDeflate(config.compression);
}

/**
Expand Down Expand Up @@ -71,3 +70,10 @@ export class Producer {
this.#track.close();
}
}

type Init = Config & { track: Moq.Track.Producer };

export namespace Producer {
/** Snapshot producer options, including the destination track. */
export type Config = Init;
}
6 changes: 3 additions & 3 deletions js/binary/src/snapshot/snapshot.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ const REPLAY_LATENCY = 30_000;

// Drain every value currently available from a fresh consumer over the (finished) track.
async function drain(track: Track.Subscriber, compression: boolean): Promise<Uint8Array[]> {
const consumer = new Consumer({ track, compression });
const consumer = new Consumer({ track, compression: compression ? "deflate" : "none" });
const out: Uint8Array[] = [];
for (;;) {
const value = await consumer.next();
Expand Down Expand Up @@ -57,7 +57,7 @@ test("a live consumer sees each update", async () => {

test("compressed roundtrip", async () => {
const track = new Track.Producer("test");
const producer = new Producer({ track, compression: true });
const producer = new Producer({ track, compression: "deflate" });
const payload = new TextEncoder().encode("the quick brown fox".repeat(64));
producer.update(payload);
producer.finish();
Expand All @@ -69,7 +69,7 @@ test("compression shrinks the frame on the wire", async () => {
// A consumer that ignored the catalog's compression flag would read this raw and get garbage,
// which is why the flag has to be carried rather than guessed.
const track = new Track.Producer("test");
const producer = new Producer({ track, compression: true });
const producer = new Producer({ track, compression: "deflate" });
const payload = new TextEncoder().encode("the quick brown fox".repeat(64));
producer.update(payload);
producer.finish();
Expand Down
19 changes: 9 additions & 10 deletions js/binary/src/stream/consumer.ts
Original file line number Diff line number Diff line change
@@ -1,14 +1,8 @@
import { Decoder as Flate } from "@moq/flate";
import type * as Moq from "@moq/net";

/** Stream consumer options, including the source track. */
export interface ConsumerConfig {
/** Track to read payloads from. */
track: Moq.Track.Subscriber;

/** Whether the frames are `deflate-raw` compressed. Must match the producer. Defaults to `false`. */
compression?: boolean;
}
import { isDeflate } from "../compression.ts";
import type { Config as CodecConfig } from "./producer.ts";

/**
* Thrown by a stream read when the track carried a second group, which a lossless log cannot do.
Expand Down Expand Up @@ -55,9 +49,9 @@ export class Consumer {
// The DEFLATE window for the group, present while decompressing.
#flate?: Flate;

constructor(config: ConsumerConfig) {
constructor(config: Consumer.Config) {
this.#track = config.track;
this.#decompress = config.compression ?? false;
this.#decompress = isDeflate(config.compression);
}

/** Get the next payload, or `undefined` once the track ends. */
Expand Down Expand Up @@ -145,3 +139,8 @@ export class Consumer {
}
}
}

export namespace Consumer {
/** Stream consumer options, including the source track. */
export type Config = CodecConfig & { track: Moq.Track.Subscriber };
}
6 changes: 3 additions & 3 deletions js/binary/src/stream/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@
* On the wire the log rides a **single group** that is never rolled, one payload per frame. A
* payload that cannot be written ends the track rather than opening a second group: a log missing a
* record is not lossless, and a gap dressed up as a complete log is worse than a visible failure.
* With {@link ProducerConfig.compression} on, that one group is one DEFLATE window, so each payload
* With {@link Config.compression} `"deflate"`, that one group is one DEFLATE window, so each payload
* compresses against the earlier ones and a run of similar payloads shrinks sharply.
*
* @module
*/

export { Consumer, type ConsumerConfig, Rolled } from "./consumer.ts";
export { Producer, type ProducerConfig } from "./producer.ts";
export { Consumer, Rolled } from "./consumer.ts";
export { type Config, Producer } from "./producer.ts";
Loading
Loading