feat(nestsClient): MoQ SUBSCRIBE family + OBJECT_DATAGRAM codecs
Phase 3c-2 of the Clubhouse/nests integration. Extends the MoQ
control-plane codec with the subscribe lifecycle messages (SUBSCRIBE,
SUBSCRIBE_OK, SUBSCRIBE_ERROR, UNSUBSCRIBE) and adds the
OBJECT_DATAGRAM wire format the listener uses to receive low-latency
Opus audio. Pure codec layer — no session-pump or network changes;
the subscribe/object delivery Flow arrives in Phase 3c-3.
commonMain (nestsclient.moq):
- New message types in `MoqMessageType`: Subscribe (0x03),
SubscribeOk (0x04), SubscribeError (0x05), Unsubscribe (0x0A).
- New data classes in MoqMessage.kt:
* `TrackNamespace` — tuple of byte strings, with `of(vararg String)`
helper for the common UTF-8 case.
* `SubscribeFilter` enum. Phase 3c-2 supports LatestGroup /
LatestObject; AbsoluteStart/AbsoluteRange throw at construction
(they need extra wire fields we'll add when nests needs them).
* `Subscribe`, `SubscribeOk`, `SubscribeError`, `Unsubscribe` data
classes. `SubscribeOk` validates contentExists + largest-id
coupling at construction.
- New codecs in `MoqCodec` (namespace tuple + all four messages).
Unknown filter codes on the wire are rejected.
- `MoqObject` data class + `MoqObjectDatagram` encode/decode for the
OBJECT_DATAGRAM wire format (track_alias, group_id, object_id,
publisher_priority, status, payload).
Tests:
- `SubscribeCodecTest` — round-trips for each message with multi-
segment namespaces + parameters, SUBSCRIBE_OK with and without
contentExists, concatenated decode in sequence, unknown-filter
rejection, construction-time validation.
- `MoqObjectDatagramTest` — Opus-sized payload round-trip, zero-
length payload with OBJECT_DOES_NOT_EXIST status, 8-byte-varint
boundary coverage, truncated datagram rejection, out-of-range
priority rejection.
https://claude.ai/code/session_013nVLALALKaHVgHm9u5Cg8D
This commit is contained in:
Claude
+103
@@ -0,0 +1,103 @@
|
||||
/*
|
||||
* Copyright (c) 2025 Vitor Pamplona
|
||||
*
|
||||
* Permission is hereby granted, free of charge, to any person obtaining a copy of
|
||||
* this software and associated documentation files (the "Software"), to deal in
|
||||
* the Software without restriction, including without limitation the rights to use,
|
||||
* copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
|
||||
* Software, and to permit persons to whom the Software is furnished to do so,
|
||||
* subject to the following conditions:
|
||||
*
|
||||
* The above copyright notice and this permission notice shall be included in all
|
||||
* copies or substantial portions of the Software.
|
||||
*
|
||||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
||||
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
||||
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
|
||||
* AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
*/
|
||||
package com.vitorpamplona.nestsclient.moq
|
||||
|
||||
import kotlin.test.Test
|
||||
import kotlin.test.assertEquals
|
||||
import kotlin.test.assertFailsWith
|
||||
|
||||
class MoqObjectDatagramTest {
|
||||
@Test
|
||||
fun encodes_and_decodes_opus_sized_payload() {
|
||||
val opusFrame = ByteArray(80) { (it and 0xFF).toByte() } // 20 ms @ 32 kbit/s Opus ≈ 80 bytes
|
||||
val obj =
|
||||
MoqObject(
|
||||
trackAlias = 7,
|
||||
groupId = 12_345,
|
||||
objectId = 42,
|
||||
publisherPriority = 0x80,
|
||||
payload = opusFrame,
|
||||
)
|
||||
val datagram = MoqObjectDatagram.encode(obj)
|
||||
val decoded = MoqObjectDatagram.decode(datagram)
|
||||
assertEquals(obj, decoded)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun zero_length_payload_round_trips() {
|
||||
val obj =
|
||||
MoqObject(
|
||||
trackAlias = 1,
|
||||
groupId = 0,
|
||||
objectId = 0,
|
||||
publisherPriority = 0,
|
||||
payload = ByteArray(0),
|
||||
status = MoqObject.STATUS_OBJECT_DOES_NOT_EXIST,
|
||||
)
|
||||
val decoded = MoqObjectDatagram.decode(MoqObjectDatagram.encode(obj))
|
||||
assertEquals(obj, decoded)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun varint_fields_respect_quic_boundaries() {
|
||||
// A large trackAlias forces an 8-byte varint, exercising the path
|
||||
// in Varint / MoqWriter / MoqReader without ambiguity.
|
||||
val obj =
|
||||
MoqObject(
|
||||
trackAlias = 1L shl 32,
|
||||
groupId = 1L shl 16,
|
||||
objectId = 1L shl 8,
|
||||
publisherPriority = 0x40,
|
||||
payload = byteArrayOf(0x01, 0x02, 0x03),
|
||||
)
|
||||
assertEquals(obj, MoqObjectDatagram.decode(MoqObjectDatagram.encode(obj)))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun truncated_datagram_is_rejected() {
|
||||
val obj =
|
||||
MoqObject(
|
||||
trackAlias = 1,
|
||||
groupId = 2,
|
||||
objectId = 3,
|
||||
publisherPriority = 0x80,
|
||||
payload = byteArrayOf(0x00, 0x01, 0x02, 0x03),
|
||||
)
|
||||
val full = MoqObjectDatagram.encode(obj)
|
||||
// Lose the bytes that carry publisher_priority + status. The remaining
|
||||
// bytes end mid-header so the reader must throw.
|
||||
val truncated = full.copyOf(3)
|
||||
assertFailsWith<MoqCodecException> { MoqObjectDatagram.decode(truncated) }
|
||||
}
|
||||
|
||||
@Test
|
||||
fun priority_out_of_range_is_rejected_at_construction() {
|
||||
assertFailsWith<IllegalArgumentException> {
|
||||
MoqObject(
|
||||
trackAlias = 1,
|
||||
groupId = 0,
|
||||
objectId = 0,
|
||||
publisherPriority = 256,
|
||||
payload = ByteArray(0),
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
+159
@@ -0,0 +1,159 @@
|
||||
/*
|
||||
* Copyright (c) 2025 Vitor Pamplona
|
||||
*
|
||||
* Permission is hereby granted, free of charge, to any person obtaining a copy of
|
||||
* this software and associated documentation files (the "Software"), to deal in
|
||||
* the Software without restriction, including without limitation the rights to use,
|
||||
* copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
|
||||
* Software, and to permit persons to whom the Software is furnished to do so,
|
||||
* subject to the following conditions:
|
||||
*
|
||||
* The above copyright notice and this permission notice shall be included in all
|
||||
* copies or substantial portions of the Software.
|
||||
*
|
||||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
||||
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
||||
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
|
||||
* AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
*/
|
||||
package com.vitorpamplona.nestsclient.moq
|
||||
|
||||
import kotlin.test.Test
|
||||
import kotlin.test.assertEquals
|
||||
import kotlin.test.assertFailsWith
|
||||
import kotlin.test.assertIs
|
||||
|
||||
class SubscribeCodecTest {
|
||||
@Test
|
||||
fun subscribe_round_trip_with_multi_segment_namespace_and_parameters() {
|
||||
val msg =
|
||||
Subscribe(
|
||||
subscribeId = 42,
|
||||
trackAlias = 7,
|
||||
namespace = TrackNamespace.of("nests", "room-abc"),
|
||||
trackName = "speaker-pubkey-hex".encodeToByteArray(),
|
||||
subscriberPriority = 0x40,
|
||||
groupOrder = 0x02,
|
||||
filter = SubscribeFilter.LatestObject,
|
||||
parameters = listOf(SetupParameter(0x10L, byteArrayOf(0x01))),
|
||||
)
|
||||
val decoded = MoqCodec.decode(MoqCodec.encode(msg))!!.message
|
||||
assertEquals(msg, assertIs<Subscribe>(decoded))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun subscribe_rejects_unsupported_filter_at_construction() {
|
||||
assertFailsWith<IllegalArgumentException> {
|
||||
Subscribe(
|
||||
subscribeId = 1,
|
||||
trackAlias = 1,
|
||||
namespace = TrackNamespace.of("ns"),
|
||||
trackName = "t".encodeToByteArray(),
|
||||
filter = SubscribeFilter.AbsoluteStart,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
fun subscribe_ok_no_content() {
|
||||
val msg =
|
||||
SubscribeOk(
|
||||
subscribeId = 42,
|
||||
expiresMs = 60_000,
|
||||
groupOrder = 2,
|
||||
contentExists = false,
|
||||
)
|
||||
val decoded = MoqCodec.decode(MoqCodec.encode(msg))!!.message
|
||||
assertEquals(msg, assertIs<SubscribeOk>(decoded))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun subscribe_ok_with_content_existing() {
|
||||
val msg =
|
||||
SubscribeOk(
|
||||
subscribeId = 3,
|
||||
expiresMs = 30_000,
|
||||
groupOrder = 1,
|
||||
contentExists = true,
|
||||
largestGroupId = 1_000,
|
||||
largestObjectId = 9,
|
||||
parameters = listOf(SetupParameter(0x20, byteArrayOf(0x01, 0x02))),
|
||||
)
|
||||
val decoded = MoqCodec.decode(MoqCodec.encode(msg))!!.message
|
||||
assertEquals(msg, assertIs<SubscribeOk>(decoded))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun subscribe_ok_construction_requires_matching_content_exists_and_largest_ids() {
|
||||
assertFailsWith<IllegalArgumentException> {
|
||||
SubscribeOk(1, 0, 0, contentExists = true)
|
||||
}
|
||||
assertFailsWith<IllegalArgumentException> {
|
||||
SubscribeOk(1, 0, 0, contentExists = false, largestGroupId = 5, largestObjectId = 1)
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
fun subscribe_error_round_trip() {
|
||||
val msg =
|
||||
SubscribeError(
|
||||
subscribeId = 9,
|
||||
errorCode = 404,
|
||||
reasonPhrase = "track not found",
|
||||
trackAlias = 9,
|
||||
)
|
||||
val decoded = MoqCodec.decode(MoqCodec.encode(msg))!!.message
|
||||
assertEquals(msg, assertIs<SubscribeError>(decoded))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun unsubscribe_round_trip() {
|
||||
val msg = Unsubscribe(subscribeId = 9_001)
|
||||
val decoded = MoqCodec.decode(MoqCodec.encode(msg))!!.message
|
||||
assertEquals(msg, assertIs<Unsubscribe>(decoded))
|
||||
}
|
||||
|
||||
@Test
|
||||
fun concatenated_subscribe_then_subscribe_ok_decode_in_sequence() {
|
||||
val sub =
|
||||
Subscribe(
|
||||
subscribeId = 1,
|
||||
trackAlias = 1,
|
||||
namespace = TrackNamespace.of("ns"),
|
||||
trackName = "t".encodeToByteArray(),
|
||||
)
|
||||
val ok = SubscribeOk(1, 5_000, 0, contentExists = false)
|
||||
val bytes = MoqCodec.encode(sub) + MoqCodec.encode(ok)
|
||||
|
||||
val first = MoqCodec.decode(bytes, offset = 0)!!
|
||||
val second = MoqCodec.decode(bytes, offset = first.bytesConsumed)!!
|
||||
|
||||
assertIs<Subscribe>(first.message)
|
||||
assertIs<SubscribeOk>(second.message)
|
||||
assertEquals(bytes.size, first.bytesConsumed + second.bytesConsumed)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun unknown_filter_code_on_wire_is_rejected_on_decode() {
|
||||
// Build a SUBSCRIBE frame with filter_type = 0x99 (not in the enum).
|
||||
val payload = MoqWriter()
|
||||
payload.writeVarint(1L) // subscribe_id
|
||||
payload.writeVarint(1L) // track_alias
|
||||
payload.writeVarint(1L) // namespace tuple size
|
||||
payload.writeLengthPrefixedString("ns")
|
||||
payload.writeLengthPrefixedString("track")
|
||||
payload.writeByte(0x80)
|
||||
payload.writeByte(0x00)
|
||||
payload.writeVarint(0x99L) // unknown filter
|
||||
payload.writeVarint(0L) // zero parameters
|
||||
|
||||
val frame = MoqWriter()
|
||||
frame.writeVarint(MoqMessageType.Subscribe.code)
|
||||
frame.writeVarint(payload.size.toLong())
|
||||
frame.writeBytes(payload.toByteArray())
|
||||
|
||||
assertFailsWith<MoqCodecException> { MoqCodec.decode(frame.toByteArray()) }
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user