diff --git a/bench/browser/page/stats.ts b/bench/browser/page/stats.ts index 1af8a34d759..cee88d035c7 100644 --- a/bench/browser/page/stats.ts +++ b/bench/browser/page/stats.ts @@ -91,7 +91,7 @@ async function allocator(connection: Moq.Connection): Promise { @@ -149,7 +149,7 @@ async function setup(config: Sampling): Promise { /** Publishes one small-frame track and plays it on every connection. */ async function receive(config: Sampling): Promise { const publishing = new Moq.Origin.Producer(); - const publication = publishing.createBroadcast(Moq.Path.from(`${config.path}/live`)); + const publication = publishing.route(Moq.Path.from(`${config.path}/live`), { hidden: true }); const track = publication.broadcast.createTrack("data", { timescale: Moq.Time.Timescale.MILLI }); publication.announce(); const publisher = await Moq.Connection.connect({ @@ -249,7 +249,7 @@ async function resume(config: Sampling & { cycles: number; idle_ms: number; limi const waits: number[] = []; for (let cycle = 0; cycle < config.cycles; cycle++) { await new Promise((resolve) => setTimeout(resolve, config.idle_ms)); - const publication = origin.createBroadcast(Moq.Path.from(`${config.path}/resume/${cycle}`)); + const publication = origin.route(Moq.Path.from(`${config.path}/resume/${cycle}`), { hidden: true }); const track = publication.broadcast.createTrack("video", { priority: 1 }); const start = performance.now(); const reservation = handle.reserve(track.demand(), 2_500_000); diff --git a/bench/browser/page/transport.ts b/bench/browser/page/transport.ts index bbfce615db6..d188ee28dc2 100644 --- a/bench/browser/page/transport.ts +++ b/bench/browser/page/transport.ts @@ -32,7 +32,7 @@ async function publish(config: Transport): Promise { // Fixture generation stays outside every timed interval. const fixtures = Array.from({ length: config.frames }, (_, frame) => payload(config.size, frame)); const origin = new Moq.Origin.Producer(); - const publication = origin.createBroadcast(Moq.Path.from(config.path)); + const publication = origin.route(Moq.Path.from(config.path), { hidden: true }); const producer = publication.broadcast; // Retention covers the whole run, so a slow consumer cannot lose a group to eviction. const track = producer.createTrack("data", { timescale: Moq.Time.Timescale.MILLI, maxAge: Milli(600_000) }); diff --git a/bench/fanout/session/Cargo.lock b/bench/fanout/session/Cargo.lock new file mode 100644 index 00000000000..2d9f2ec521d --- /dev/null +++ b/bench/fanout/session/Cargo.lock @@ -0,0 +1,840 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "arrayvec" +version = "0.7.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56" + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "chacha20" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06" +dependencies = [ + "cfg-if", + "cpufeatures", + "rand_core", +] + +[[package]] +name = "cpufeatures" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566" +dependencies = [ + "libc", +] + +[[package]] +name = "crc32fast" +version = "1.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5f97d3416d5337d15c4b0d78c8c91df922ca143f57ec20e2d1c188333047ef04" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "crossbeam-epoch" +version = "0.9.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc74980687109a3b14c72fd458107bf0baa1da1a1a805e178d15501ba9b86d9d" +dependencies = [ + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-utils" +version = "0.8.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6" + +[[package]] +name = "displaydoc" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "equivalent" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826" + +[[package]] +name = "fanout-session" +version = "0.0.0" +dependencies = [ + "bytes", + "futures", + "kio", + "moq-net", + "tokio", +] + +[[package]] +name = "flate2" +version = "1.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb" +dependencies = [ + "crc32fast", + "zlib-rs", +] + +[[package]] +name = "foldhash" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "futures" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3" +dependencies = [ + "futures-channel", + "futures-core", + "futures-executor", + "futures-io", + "futures-sink", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-channel" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4" +dependencies = [ + "futures-core", + "futures-sink", +] + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-executor" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-io" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed" + +[[package]] +name = "futures-macro" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "futures-sink" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-channel", + "futures-core", + "futures-io", + "futures-macro", + "futures-sink", + "futures-task", + "memchr", + "pin-project-lite", + "slab", +] + +[[package]] +name = "getrandom" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" +dependencies = [ + "cfg-if", + "libc", + "r-efi", + "rand_core", +] + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" +dependencies = [ + "foldhash", +] + +[[package]] +name = "hashlink" +version = "0.12.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a596f1b20ed2cc5ecac41a164aaebc7258057060f06c0cf7a2ba3991ee7990fb" +dependencies = [ + "hashbrown", +] + +[[package]] +name = "icu_collections" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe090a42a0d3140fed8c63263ed1fecc02422cb2f4bfe55cd8de2de1b8e105dd" +dependencies = [ + "displaydoc", + "potential_utf", + "utf8_iter", + "yoke", + "zerofrom", + "zerovec", +] + +[[package]] +name = "icu_locale_core" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "25d29b57c17c6528d0dc4c2141cfa2d08200465acb537a3909c8b9b8a4a984c0" +dependencies = [ + "displaydoc", + "litemap", + "tinystr", + "writeable", + "zerovec", +] + +[[package]] +name = "icu_normalizer" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "404a3b8c486f205c87fe7f23ab6894d84a4ad76d6e4671ae1981ba7def87c599" +dependencies = [ + "icu_collections", + "icu_normalizer_data", + "icu_properties", + "icu_provider", + "smallvec", + "zerovec", +] + +[[package]] +name = "icu_normalizer_data" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20f0088bfb7441f7a37fa0c9e20cb1e9cba1cac6b9ce8cd2a6dc44294f8e8cbc" + +[[package]] +name = "icu_properties" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ea83d991c56158f7cf898bf86436c1dfe7c07ee82fe88951f2695c9f37a379f" +dependencies = [ + "displaydoc", + "icu_collections", + "icu_locale_core", + "icu_properties_data", + "icu_provider", + "zerotrie", + "zerovec", +] + +[[package]] +name = "icu_properties_data" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b98f29af82d02b163fe50161388350e743bb3107cc8e8c2f7314cb505faddfcf" + +[[package]] +name = "icu_provider" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "413099315636c588ee8f011190b329b971a09a8fae9d157e01dcae8379468514" +dependencies = [ + "displaydoc", + "icu_locale_core", + "writeable", + "yoke", + "zerofrom", + "zerotrie", + "zerovec", +] + +[[package]] +name = "idna" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de" +dependencies = [ + "idna_adapter", + "smallvec", + "utf8_iter", +] + +[[package]] +name = "idna_adapter" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714" +dependencies = [ + "icu_normalizer", + "icu_properties", +] + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown", +] + +[[package]] +name = "kio" +version = "0.6.2" +dependencies = [ + "crossbeam-epoch", + "kio-macros", + "rand", + "smallvec", + "tokio", +] + +[[package]] +name = "kio-macros" +version = "0.1.0" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "litemap" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "moq-net" +version = "0.3.10" +dependencies = [ + "arrayvec", + "bytes", + "flate2", + "futures", + "hashbrown", + "hashlink", + "kio", + "moq-pattern", + "num_enum", + "rand", + "rangemap", + "serde", + "slab", + "thiserror", + "tracing", + "url", +] + +[[package]] +name = "moq-pattern" +version = "0.1.2" +dependencies = [ + "serde", +] + +[[package]] +name = "num_enum" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d0bca838442ec211fa11de3a8b0e0e8f3a4522575b5c4c06ed722e005036f26" +dependencies = [ + "num_enum_derive", + "rustversion", +] + +[[package]] +name = "num_enum_derive" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8" +dependencies = [ + "proc-macro-crate", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "potential_utf" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661" +dependencies = [ + "zerovec", +] + +[[package]] +name = "proc-macro-crate" +version = "3.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f" +dependencies = [ + "toml_edit", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + +[[package]] +name = "rand" +version = "0.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65c9fb96cbc91e3478eaae79a69fcd3f1ae4ad052e471fe6732fff548984b4af" +dependencies = [ + "chacha20", + "getrandom", + "rand_core", +] + +[[package]] +name = "rand_core" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69" + +[[package]] +name = "rangemap" +version = "1.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a611d15b50743feb4c76b7d03edcb0e64f399c26961e4efe6975bc398be6aa3d" + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "smallvec" +version = "1.16.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0d5d4b1981b8bbbb7aed204cae5726d683d5d6ac7e74ec54122ea28f315e7c8" + +[[package]] +name = "stable_deref_trait" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "synstructure" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "tinystr" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "abc840c238154d58f9e86b2792261edfde565a17696e1cda1a449de27979801a" +dependencies = [ + "displaydoc", + "zerovec", +] + +[[package]] +name = "tokio" +version = "1.54.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b52fd3255258d26fac7264ab5a76b53c13367136dc011d3d6ad4f8ed070396a3" +dependencies = [ + "pin-project-lite", +] + +[[package]] +name = "toml_datetime" +version = "1.1.2+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b86d767906c6c42421dcba507eb9d203e779497710a47782a224bb871653053" +dependencies = [ + "serde_core", +] + +[[package]] +name = "toml_edit" +version = "0.25.18+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ec6e78bd70db9420d8d212fa9dc97f116448a1ceff5d00eabb991d407e21396" +dependencies = [ + "indexmap", + "toml_datetime", + "toml_parser", + "winnow", +] + +[[package]] +name = "toml_parser" +version = "1.1.5+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c" +dependencies = [ + "winnow", +] + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "pin-project-lite", + "tracing-attributes", + "tracing-core", +] + +[[package]] +name = "tracing-attributes" +version = "0.1.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", +] + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "url" +version = "2.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed" +dependencies = [ + "form_urlencoded", + "idna", + "percent-encoding", + "serde", +] + +[[package]] +name = "utf8_iter" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af3bd9d3e571c26fcce9d033b87ea5ab061b8d2ffe9b7a5675d810d68f03edf0" +dependencies = [ + "utf_types", +] + +[[package]] +name = "utf_types" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a3b425286980a367278453f3b6d28cdcb134b574e5a35824a6ff5eebad50bb6" + +[[package]] +name = "winnow" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8c3b93199df0ab874cdf0c6a94f0a0dc3423fe41f1cafb62b8bd7b1deb277aef" +dependencies = [ + "memchr", +] + +[[package]] +name = "writeable" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc" + +[[package]] +name = "yoke" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "417ef3fcf6c300b7dbd25c85531a746931c02ad536f3cf4786ed1e88223340b3" +dependencies = [ + "stable_deref_trait", + "yoke-derive", + "zerofrom", +] + +[[package]] +name = "yoke-derive" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", + "synstructure", +] + +[[package]] +name = "zerofrom" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272" +dependencies = [ + "zerofrom-derive", +] + +[[package]] +name = "zerofrom-derive" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", + "synstructure", +] + +[[package]] +name = "zerotrie" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f" +dependencies = [ + "displaydoc", + "yoke", + "zerofrom", +] + +[[package]] +name = "zerovec" +version = "0.11.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f58a2799cfe9a1670c7ea8edbd52ef8edb93cb37a7f83bf31ba9e35d9dae6a40" +dependencies = [ + "yoke", + "zerofrom", + "zerovec-derive", +] + +[[package]] +name = "zerovec-derive" +version = "0.11.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3743ddbf47738d929cd1ae2e199d40d0162979dfe31aef8ae646d2bf00bf97a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "zlib-rs" +version = "0.6.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112" diff --git a/bench/fanout/session/src/main.rs b/bench/fanout/session/src/main.rs index 6c841192bd7..03e7f3d27fb 100644 --- a/bench/fanout/session/src/main.rs +++ b/bench/fanout/session/src/main.rs @@ -63,10 +63,10 @@ fn main() { .with_subscriber(relay.clone()), ) .await; - let broadcast = publisher.create_broadcast("room").unwrap(); + let broadcast = publisher.route("room", moq_net::origin::RouteOptions::hidden()).unwrap(); let info = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); - let mut track = broadcast.create_track("chat", info).unwrap(); - broadcast.announce(Default::default()).unwrap(); + let mut track = broadcast.broadcast().create_track("chat", info).unwrap(); + broadcast.announce().unwrap(); let mut audience = Vec::new(); for viewer in 0..viewers { diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index 8c738b9bda8..e12e9ed5a8d 100644 --- a/c/moq/MIGRATE.md +++ b/c/moq/MIGRATE.md @@ -4,6 +4,18 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Publishing goes through one `moq_route` handle + +`moq_origin_producer_create_broadcast(origin, path, &publication)` is `moq_origin_producer_route(origin, path, &options, &route)`, and `moq_origin_producer_requests(origin, prefix, &requests)` is `moq_origin_producer_route_prefix(origin, prefix, &options, &route)`; start `options` from `moq_route_options_default()`. A `moq_route` replaces `moq_publication`, `moq_origin_requests`, and `moq_broadcast_prepared`: + +- `moq_publication_broadcast(publication)` is `moq_route_broadcast(route, &broadcast)`, which fails on a prefix route. +- `moq_publication_announce(publication, &route)` is `moq_route_announce(route)`, and re-pricing is `moq_route_set_cost(route, cost)`; `moq_publication_unannounce` is `moq_route_withdraw`. +- `moq_origin_requests_requested_broadcast` is `moq_route_requested`, whose value is NULL once the origin closes. +- `moq_broadcast_request_prepare` then `moq_broadcast_prepared_publish` is `moq_broadcast_request_route(request, &options, &route)`: create it hidden to fill it first, then announce it. +- `moq_route_instance_id(route)` returns the stream's instance, kept across withdraw and announce. + +`moq_announce_route` is `moq_route_options`, given at creation, with a leading `hidden`. The default route is visible at once, so set `hidden` and call `moq_route_announce` after filling the catalog to keep the old order. Hold the route while the broadcast should stay announced: `moq_route_cancel` or freeing its last handle retracts it, and `moq_broadcast_producer_close` ends both. The `moq_route` record on `moq_announce.route` is `moq_route_info`. + ### Separate datagram tracks Create a separate producer with `moq_publish_datagrams` and `moq_datagram_info`; replace `moq_publish_track_datagram` with `moq_publish_datagrams_append` on that handle, or `moq_publish_datagrams_insert` for an explicit sequence. `moq_consume_datagrams` now takes a subscriber priority before its callback and never subscribes to a stream track. Use `moq_publish_datagrams_demand` and `moq_datagram_demand_priority` for aggregate priority, and `moq_publish_datagrams_requests` / `moq_datagram_request_accept` for on-demand publishing. Finish or abort datagram producers separately. A zeroed datagram info is untimed, unlike the microsecond default of stream-track info. diff --git a/c/moq/test/probe.c b/c/moq/test/probe.c index 5ab02854386..6ca21f6ee1f 100644 --- a/c/moq/test/probe.c +++ b/c/moq/test/probe.c @@ -288,18 +288,22 @@ int main(void) /* Publisher: a server whose origin serves one broadcast with one track. */ moq_origin_config origin_config = moq_origin_config_default(); moq_origin_producer *origin = moq_origin_producer_new(&origin_config); - moq_publication *publication = NULL; - ok(moq_origin_producer_create_broadcast(origin, "probe", &publication), "create_broadcast"); - moq_broadcast_producer *broadcast = moq_publication_broadcast(publication); + /* Hidden until its track exists; the route keeps it announced while it is held. */ + moq_route_options route_options = moq_route_options_default(); + route_options.hidden = true; + moq_route *route = NULL; + ok(moq_origin_producer_route(origin, "probe", &route_options, &route), "route"); + moq_broadcast_producer *broadcast = NULL; + ok(moq_route_broadcast(route, &broadcast), "route broadcast"); + char *instance = moq_route_instance_id(route); + CHECK(instance && instance[0] != '\0'); + moq_string_free(instance); moq_track_info info = moq_track_info_default(); info.timescale.has_value = true; info.timescale.value = 1000000; moq_track_producer *track = NULL; ok(moq_broadcast_producer_publish_track(broadcast, "data", &info, &track), "publish_track"); - moq_announce_route route = moq_announce_route_default(); - ok(moq_publication_announce(publication, &route), "announce"); - /* Releasing the publication keeps the route: the subscriber below still reaches it. */ - moq_publication_free(publication); + ok(moq_route_announce(route), "announce"); const char *generate[] = {"localhost"}; const char *versions[] = {"moq-lite-07-wip"}; @@ -419,6 +423,7 @@ int main(void) moq_server_free(server); moq_track_producer_free(track); moq_broadcast_producer_free(broadcast); + moq_route_free(route); moq_origin_producer_free(origin); /* A first dial that keeps failing still returns the session, whose state names each failed @@ -455,10 +460,13 @@ int main(void) * while moq_shutdown drains the dispatcher; none may run once it returns, even as the * handles are freed afterward. */ moq_origin_producer *late_origin = moq_origin_producer_new(&origin_config); - moq_publication *late_publication = NULL; - ok(moq_origin_producer_create_broadcast(late_origin, "late", &late_publication), "late broadcast"); - moq_broadcast_producer *late_broadcast = moq_publication_broadcast(late_publication); - moq_publication_free(late_publication); + moq_route_options late_options = moq_route_options_default(); + late_options.hidden = true; + moq_route *late_route = NULL; + ok(moq_origin_producer_route(late_origin, "late", &late_options, &late_route), "late route"); + moq_broadcast_producer *late_broadcast = NULL; + ok(moq_route_broadcast(late_route, &late_broadcast), "late broadcast"); + moq_route_free(late_route); moq_track_producer *late_track = NULL; ok(moq_broadcast_producer_publish_track(late_broadcast, "data", &info, &late_track), "late track"); moq_track_consumer *late = NULL; diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index b3a688e0dca..b915c08031a 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -6,6 +6,18 @@ `moq::Following::available()` resolves to a null `std::shared_ptr` once the path goes offline (or, for a follow pinned to an instance, once another instance takes it over), then the next broadcast when something serves the path again. The first call is never null. Check for null before using a later result, and treat it like the previous instance ending. +### Publishing goes through one `moq::Route` handle + +`OriginProducer::create_broadcast(path)` is `route(path, options)`, and `requests(prefix)` is `route_prefix(prefix, options)`; `{}` options are the default. Each returns a `std::shared_ptr`, which replaces `moq::Publication`, `moq::OriginRequests`, and `moq::BroadcastPrepared`: + +- `Publication::broadcast()` is `Route::broadcast()`, which returns an error on a prefix route. +- `Publication::announce(route)` is `announce()`, and re-pricing is `set_cost(cost)`; `unannounce()` is `withdraw()`. +- `OriginRequests::requested_broadcast()` is `requested()`, which resolves to `nullptr` once the origin closes. +- `BroadcastRequest::prepare()` then `BroadcastPrepared::publish()` is `BroadcastRequest::route(options)`: create it hidden to fill it first, then `announce()`. +- `instance_id()` is the stream's instance, kept across `withdraw()` and `announce()`. + +`moq::AnnounceRoute` is `moq::RouteOptions{hidden, cost, instance, epoch}`, given at creation. A route is visible at once unless `hidden`; set it and call `announce()` after filling the catalog to keep the old order. Hold the route while the broadcast should stay announced: `cancel()` or releasing its last handle retracts it, and closing its broadcast ends both. `moq::Route`, the record on `moq::Announce::route`, is `moq::RouteInfo`. + ### Separate datagram tracks Replace stream-track datagram methods with `BroadcastProducer::create_datagrams(name, info)` and `BroadcastConsumer::datagrams(name)`. The generated `DatagramProducer` exposes `append(timestamp, payload)` and `insert(Datagram)`; `DatagramConsumer::recv()` returns an optional datagram through a future. `DatagramInfo` has only priority and optional timescale. Demand is aggregate subscriber `priority()` / `priority_changed(last)`; on-demand datagram requests come from `BroadcastRequests::datagrams()` / `DatagramRequests::requested()`. Stream tracks of the same name are independent. diff --git a/cpp/moq/bench/main.cpp b/cpp/moq/bench/main.cpp index 91653e4326c..dde2857309f 100644 --- a/cpp/moq/bench/main.cpp +++ b/cpp/moq/bench/main.cpp @@ -98,7 +98,10 @@ Reader read(Case c, std::shared_ptr consumer, const std::vec void throughput(Case c, double budget, std::vector &results) { auto origin = moq::OriginProducer::init({uint64_t(64 << 20)}); - auto broadcast = ok(origin->create_broadcast("bench"))->broadcast(); + moq::RouteOptions hidden; + hidden.hidden = true; + auto route = ok(origin->route("bench", hidden)); + auto broadcast = ok(route->broadcast()); std::vector> tracks; std::vector> consumers; moq::TrackInfo info; diff --git a/cpp/moq/test/probe.cpp b/cpp/moq/test/probe.cpp index ffea5252058..e4f325ebade 100644 --- a/cpp/moq/test/probe.cpp +++ b/cpp/moq/test/probe.cpp @@ -293,24 +293,23 @@ int main() // It prints the message Rust's Display gives. CHECK(fingerprints.error().to_string() == "bind: not listening; call listen() first"); - // Publisher: a server whose origin serves one broadcast with one track. Dropping the - // publication keeps the route, which lasts until the broadcast closes. + // Publisher: a server whose origin serves one broadcast with one track. The route, created + // hidden until its track exists, keeps the broadcast announced while it is held. auto origin = moq::OriginProducer::init({}); - std::shared_ptr broadcast; - std::shared_ptr track; - { - auto publication = ok(origin->create_broadcast("probe"), "create_broadcast"); - broadcast = publication->broadcast(); - moq::TrackInfo info; - info.timescale = 1000000; - track = ok(broadcast->publish_track("data", info), "publish_track"); - ok(publication->announce({}), "announce"); - } - - // A closed broadcast's publication can no longer announce. - auto stale = ok(origin->create_broadcast("stale"), "create_broadcast"); - ok(stale->broadcast()->close(), "close stale broadcast"); - auto reannounced = stale->announce({}); + moq::RouteOptions hidden; + hidden.hidden = true; + auto route = ok(origin->route("probe", hidden), "route"); + CHECK(!route->instance_id().empty()); + auto broadcast = ok(route->broadcast(), "route broadcast"); + moq::TrackInfo info; + info.timescale = 1000000; + auto track = ok(broadcast->publish_track("data", info), "publish_track"); + ok(route->announce(), "announce"); + + // A route whose broadcast closed can no longer announce. + auto stale = ok(origin->route("stale", {}), "route"); + ok(ok(stale->broadcast(), "stale broadcast")->close(), "close stale broadcast"); + auto reannounced = stale->announce(); CHECK(!reannounced); CHECK(std::holds_alternative(reannounced.error().get_variant())); diff --git a/cpp/obs/src/moq-dock.cpp b/cpp/obs/src/moq-dock.cpp index 21699589dd2..02eb02b029f 100644 --- a/cpp/obs/src/moq-dock.cpp +++ b/cpp/obs/src/moq-dock.cpp @@ -1124,6 +1124,11 @@ void MoQDock::StartStream() return; } + if (auto *moq = static_cast(obs_obj_get_data(output))) { + const auto instance = moq->GetInstance(); + if (!instance.empty()) + publishSummary += QStringLiteral("\nInstance ") + QString::fromStdString(instance); + } pollTimer->start(); SetRunning(true); diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index 95bfb576647..df628cfda75 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -166,19 +166,20 @@ bool MoQOutput::Start() return false; } - // Create the broadcast on an origin of our own, then announce it so subscribers - // can discover it. Stop() finishes it, so each Start creates a fresh one, under a - // fresh instance the broadcast mints and keeps across reconnects. Only the - // broadcast is kept: the route outlives the publication until the broadcast closes. + // Route the broadcast on an origin of our own, visible at once so subscribers can + // discover it. Stop() closes it, so each Start creates a fresh route, under a fresh + // instance it mints and keeps across reconnects. The route is held until Reset(): + // releasing it would retract the broadcast. LOG_INFO("Publishing broadcast: %s", path.c_str()); auto next_origin = moq::OriginProducer::init(moq::OriginConfig{}); - auto publication = next_origin->create_broadcast(path); - if (!publication) { - LOG_ERROR("Failed to create broadcast: %s", publication.error().to_string().c_str()); + auto next_route = next_origin->route(path, {}); + if (!next_route) { + LOG_ERROR("Failed to create broadcast: %s", next_route.error().to_string().c_str()); return false; } - if (auto announced = (*publication)->announce({}); !announced) { - LOG_ERROR("Failed to announce broadcast: %s", announced.error().to_string().c_str()); + auto next_broadcast = (*next_route)->broadcast(); + if (!next_broadcast) { + LOG_ERROR("Failed to create broadcast: %s", next_broadcast.error().to_string().c_str()); return false; } @@ -228,11 +229,13 @@ bool MoQOutput::Start() { std::lock_guard lock(mutex); url = server; + instance = (*next_route)->instance_id(); } { std::lock_guard lock(media_mutex); origin = next_origin; - broadcast = (*publication)->broadcast(); + route = *next_route; + broadcast = *next_broadcast; } // NOTE: You could publish the same broadcasts to multiple sessions if you want (redundant ingest). @@ -369,6 +372,7 @@ void MoQOutput::Reset() connected = false; live = false; url.clear(); + instance.clear(); last_failure_code = MoQError::None; last_failure_reason.clear(); token_refusal.clear(); @@ -403,6 +407,7 @@ void MoQOutput::Reset() if (broadcast) broadcast->close(); broadcast.reset(); + route.reset(); origin.reset(); // The session owns the drain after this request, even if the output dies now. @@ -425,6 +430,12 @@ void MoQOutput::Reset() SetBitrate(encoder, bitrate); } +std::string MoQOutput::GetInstance() +{ + std::lock_guard lock(mutex); + return instance; +} + bool MoQOutput::TryGetConnectionStats(ConnectionStats *out) { if (!out) diff --git a/cpp/obs/src/moq-output.h b/cpp/obs/src/moq-output.h index 796c5e516e1..333528baf39 100644 --- a/cpp/obs/src/moq-output.h +++ b/cpp/obs/src/moq-output.h @@ -59,6 +59,9 @@ class MoQOutput { // Prefer this over obs_output_get_connect_time_ms, which stays 0 for sub-ms connects. bool IsLiveSession(); + // The route's instance for this Start(), kept through session reconnects; empty when stopped. + std::string GetInstance(); + // Most recent connect/reconnect failure for this Start(), or empty when none. // Thread-safe; the dock polls this while connecting, while reconnecting, and on stop. void CopyLastFailure(int *code, std::string *reason); @@ -184,6 +187,7 @@ class MoQOutput { bool connected = false; bool live = false; std::string url; + std::string instance; int last_failure_code = 0; std::string last_failure_reason; std::string token_refusal; @@ -195,6 +199,8 @@ class MoQOutput { // Never held across an OBS call that can wait on an encoder thread. std::mutex media_mutex; std::shared_ptr origin; + // Keeps the broadcast announced; the broadcast closing retracts it. + std::shared_ptr route; std::shared_ptr broadcast; std::map video_tracks; std::map audio_tracks; diff --git a/cpp/obs/test/moq-audio-encoder-test.cpp b/cpp/obs/test/moq-audio-encoder-test.cpp index f7f19fd9b15..682658d1ebb 100644 --- a/cpp/obs/test/moq-audio-encoder-test.cpp +++ b/cpp/obs/test/moq-audio-encoder-test.cpp @@ -203,9 +203,8 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) return; auto origin = moq::OriginProducer::init(moq::OriginConfig{}); - auto publication = TestOk(origin->create_broadcast("room"), "create_broadcast"); - auto broadcast = publication->broadcast(); - TestOk(publication->announce({}), "announce"); + auto route = TestOk(origin->route("room", {}), "route"); + auto broadcast = TestOk(route->broadcast(), "route broadcast"); moq::AudioInit init{}; init.format = moq::AudioFormat::kOpus; diff --git a/cpp/obs/test/moq-source-test.cpp b/cpp/obs/test/moq-source-test.cpp index 91a11c9690d..740e0bb3e77 100644 --- a/cpp/obs/test/moq-source-test.cpp +++ b/cpp/obs/test/moq-source-test.cpp @@ -585,8 +585,10 @@ class Publisher { uint64_t start_us = 1'000'000) : timestamp_us(start_us) { - auto publication = TestOk(relay.origin->create_broadcast(path), "create_broadcast"); - broadcast = publication->broadcast(); + moq::RouteOptions hidden; + hidden.hidden = true; + route = TestOk(relay.origin->route(path, hidden), "route"); + broadcast = TestOk(route->broadcast(), "route broadcast"); if (video) { moq::VideoInit init{}; init.format = moq::VideoFormat::kAvc3; @@ -603,7 +605,7 @@ class Publisher { TestOk(moq::MediaTrackProducer::audio(broadcast, moq::MediaTarget::kNamed{}, init), "audio producer"); } - TestOk(publication->announce(moq::AnnounceRoute{}), "announce"); + TestOk(route->announce(), "announce"); } ~Publisher() { (void)broadcast->close(); } @@ -632,6 +634,8 @@ class Publisher { timeout); } + // Keeps the broadcast announced for the publisher's lifetime. + std::shared_ptr route; std::shared_ptr broadcast; std::shared_ptr video; std::shared_ptr audio; @@ -1576,9 +1580,13 @@ int main() auto snapshot = TestOk(catalogs->next().get(), "catalog snapshot"); CHECK(snapshot.has_value()); auto config = snapshot->video.begin()->second; - std::shared_ptr hidden; + std::shared_ptr hidden; if (sibling) { - hidden = TestOk(relay.origin->create_broadcast("obs/hidden"), "unannounced sibling"); + // A different stream than the one the rendition pins, hidden until announced. + moq::RouteOptions options; + options.hidden = true; + options.instance = "obs-test-other"; + hidden = TestOk(relay.origin->route("obs/hidden", options), "unannounced sibling"); config.broadcast = "./hidden"; config.instance = "obs-test-pinned"; } @@ -1601,9 +1609,7 @@ int main() const int frames = g_output_frames; CHECK(publisher.WriteUntil([&] { return g_output_frames >= frames + 3; })); // A different stream is a real resolution failure. - moq::AnnounceRoute route; - route.instance = "obs-test-other"; - TestOk(hidden->announce(route), "announce mismatched sibling"); + TestOk(hidden->announce(), "announce mismatched sibling"); } CHECK(WaitFor([] { std::lock_guard lock(g_candidate_mutex); diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index f2edcc86509..ea8860a333e 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -26,6 +26,17 @@ while (true) { } ``` +### Publishing goes through one `MoqRoute` handle + +`Moq.createBroadcast(path)`, `Server.createBroadcast(path)`, and `OriginProducer.createBroadcast(path: ...)` are `route(path, options: ...)` (`route(path: ..., options: RouteOptions())` on the generated `OriginProducer`), and `OriginProducer.requests(prefix: ...)` is `routePrefix(prefix: ..., options: RouteOptions())`. Each returns a `MoqRoute`, which replaces `Publication`, `OriginRequests`, and `BroadcastPrepared`: + +- `Publication.announce(route: AnnounceRoute(...))` is `announce()`, and re-pricing is `setCost(cost: ...)`; `unannounce()` is `withdraw()`. +- `OriginRequests.requestedBroadcast()` is `requested()`, which returns `null` once the origin closes. +- `BroadcastRequest.prepare()` then `publish()` is `BroadcastRequest.route(options: ...)`: create it hidden to fill it first, then `announce()`. +- `instance()` is the stream's instance, kept across `withdraw()` and `announce()`. + +`AnnounceRoute` is `RouteOptions(hidden:, cost:, instance:, epoch:)`, given at creation. A route is visible at once unless `hidden: true`; pass it and call `announce()` after filling the catalog to keep the old order. Hold the route while the broadcast should stay announced: cancelling or disposing it retracts it, and closing its broadcast ends both. `MoqRoute`, the facts on `Announce.route`, is `RouteInfo` (`MoqRouteInfo`), and the route handle keeps the `Moq` prefix because Flutter owns `Route`. + ### Catalog renditions carry their warmup ([#7864](https://github.com/moq-dev/moq/pull/7864)) `Video` and `Audio` gain `warmup`, the catalog's decoder warmup; it defaults to `null`, so existing constructors still compile. `TrackConsumer` and the audio and video consumers read it from the rendition and start that much earlier. diff --git a/dart/moq/README.md b/dart/moq/README.md index c6ccb9272be..d33323de046 100644 --- a/dart/moq/README.md +++ b/dart/moq/README.md @@ -33,12 +33,12 @@ final server = await Server.listen( tlsGenerate: ['localhost'], ), ); -final publication = server.createBroadcast('live'); -publication.announce(route: AnnounceRoute()); // unannounced broadcasts are invisible +final route = server.route('live'); // hold it: disposing the route retracts it await for (final request in server.requests()) { final session = await request.accept(); print(session.state().connects); } +route.dispose(); // retracts the route ``` The package uses `Future` for asynchronous operations and `Stream` for diff --git a/dart/moq/bench/ffi.dart b/dart/moq/bench/ffi.dart index a4defdca85c..e1626e44531 100644 --- a/dart/moq/bench/ffi.dart +++ b/dart/moq/bench/ffi.dart @@ -41,8 +41,11 @@ Future throughput( final origin = OriginProducer( config: OriginConfig(cacheCapacityBytes: 64 << 20), ); - final publication = origin.createBroadcast(path: 'bench'); - final broadcast = publication.broadcast(); + final route = origin.route( + path: 'bench', + options: RouteOptions(hidden: true), + ); + final broadcast = route.broadcast(); final tracks = List.generate( c.publishers, (p) => @@ -124,7 +127,7 @@ Future throughput( track.dispose(); } broadcast.dispose(); - publication.dispose(); + route.dispose(); origin.dispose(); } } diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 478853db830..e456a825512 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -13,7 +13,8 @@ import 'package:moq_ffi/moq_ffi.dart'; // // * `MoqServer` - `Server` is the listen facade in server.dart. // * `MoqContainer` / `MoqRoute` - `Container` and `Route` are Flutter's, and -// an ambiguous import would break every Flutter app that uses them. +// an ambiguous import would break every Flutter app that uses them. Its +// options and facts are still [RouteOptions] and [RouteInfo]. // * `MoqException` - `Exception` is in `dart:core`. /// A MoQ client: configure the TLS/bind knobs, then connect to a relay. @@ -37,7 +38,7 @@ typedef CongestionControl = MoqCongestionControl; /// Certificate trust and the mTLS identity for `ConnectOptions.tls`. typedef ClientTls = MoqClientTls; -/// The publish side of an origin: create broadcasts so subscribers can discover them. +/// The publish side of an origin: create routes so subscribers can discover their broadcasts. typedef OriginProducer = MoqOriginProducer; /// Config for creating an origin, such as its total cache budget. @@ -46,17 +47,11 @@ typedef OriginConfig = MoqOriginConfig; /// The subscribe side of an origin: discover and request published broadcasts. typedef OriginConsumer = MoqOriginConsumer; -/// A served route: advertises a path prefix and yields broadcast requests beneath it. -typedef OriginRequests = MoqOriginRequests; - -/// A requested broadcast not yet accepted: fulfill it with a producer or reject it. +/// A requested broadcast not yet answered: serve a held broadcast, route a new one, or reject it. typedef BroadcastRequest = MoqBroadcastRequest; -/// A claim answer being filled before its exact route is announced. -typedef BroadcastPrepared = MoqBroadcastPrepared; - -/// A broadcast published on an origin: the broadcast to fill and its announcement. -typedef Publication = MoqPublication; +/// How a route advertises itself: hidden until announced, its static cost, and a stable instance. +typedef RouteOptions = MoqRouteOptions; /// A stream of announce events under a prefix. typedef AnnounceConsumer = MoqAnnounceConsumer; @@ -67,8 +62,8 @@ typedef AnnounceConfig = MoqAnnounceConfig; /// Follows a specific broadcast path across the publisher instances that serve it. typedef Following = MoqFollowing; -/// How a broadcast advertises its exact path: its static production cost and stream instance. -typedef AnnounceRoute = MoqAnnounceRoute; +/// The read-only facts on a received route: hops, a static cost, and the stream's instance. +typedef RouteInfo = MoqRouteInfo; /// A route over a prefix: its origin-relative path, required wildcard captures (empty without wildcards), and route metadata. typedef Announce = MoqAnnounce; diff --git a/dart/moq/lib/src/client.dart b/dart/moq/lib/src/client.dart index 18e7964173a..4bcaebbca9f 100644 --- a/dart/moq/lib/src/client.dart +++ b/dart/moq/lib/src/client.dart @@ -213,13 +213,14 @@ final class Moq { } } - /// Create an unannounced broadcast at [path], invisible to everyone until announced. + /// Create a route at exactly [path], owning a new broadcast to fill. /// - /// Populate its `broadcast`, calling `requests` first if tracks are served - /// on demand, then advertise it with `announce`. Disposing the publication - /// keeps the route; closing the broadcast ends it. - Publication createBroadcast(String path) => - session.publish().createBroadcast(path: path); + /// Visible at once unless [options] is hidden: create it hidden to populate + /// its `broadcast()` first (calling `requests` if tracks are served on + /// demand), then `announce()` it. Hold the route: cancelling or disposing it + /// retracts it, and closing the broadcast ends both. + MoqRoute route(String path, {RouteOptions? options}) => + session.publish().route(path: path, options: options ?? RouteOptions()); /// List the paths matching [options] as each becomes present or absent; /// prefixes stay relative to the origin. diff --git a/dart/moq/lib/src/server.dart b/dart/moq/lib/src/server.dart index 1a127b4e4aa..81acee86a89 100644 --- a/dart/moq/lib/src/server.dart +++ b/dart/moq/lib/src/server.dart @@ -53,7 +53,7 @@ final class ListenOptions { /// A listening MoQ server with publishing and subscription conveniences. /// -/// Build one with [Server.listen]. Broadcasts created via [createBroadcast] are +/// Build one with [Server.listen]. Broadcasts of routes created via [route] are /// served to incoming sessions, and [requests] streams each incoming [Request] /// for the caller to accept or reject. [close] stops accepting new sessions and /// releases the listening socket before it returns; in-flight sessions stay @@ -111,15 +111,16 @@ final class Server { } } - /// Create a broadcast at [path], served to incoming sessions. + /// Create a route at exactly [path], owning a broadcast served to incoming sessions. /// - /// Advertise it with `announce` after populating its `broadcast`. Throws - /// when [listen] was given a [ListenOptions.consume] origin but no - /// [ListenOptions.publish] one, since there is then nothing to serve from. - Publication createBroadcast(String path) { + /// Visible at once unless [options] is hidden; hold the route, since + /// cancelling or disposing it retracts it. Throws when [listen] was given a + /// [ListenOptions.consume] origin but no [ListenOptions.publish] one, since + /// there is then nothing to serve from. + MoqRoute route(String path, {RouteOptions? options}) { final origin = _publishOrigin; if (origin == null) throw StateError('no publish origin configured'); - return origin.createBroadcast(path: path); + return origin.route(path: path, options: options ?? RouteOptions()); } /// SHA-256 fingerprints of the configured TLS certificates, hex-encoded. diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index ffcc9daf1c8..0e6d525cf5b 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -281,12 +281,15 @@ void main() { final announcement = client.announced().updates().firstWhere( (event) => event is AnnounceEventPresent, ); - final publication = relay.createBroadcast(path: 'live'); - final track = publication.broadcast().publishTrack( + final route = relay.route( + path: 'live', + options: RouteOptions(hidden: true), + ); + final track = route.broadcast().publishTrack( name: 'events', info: TrackInfo(timescale: 1000000), ); - publication.announce(route: AnnounceRoute()); + route.announce(); final announced = (await announcement.timeout(timeout) as AnnounceEventPresent).announce; expect(announced.prefix, 'live'); @@ -370,10 +373,10 @@ void main() { final announcement = client.announced().updates().firstWhere( (event) => event is AnnounceEventPresent, ); - final publication = server.createBroadcast('live'); - final broadcast = publication.broadcast(); + final route = server.route('live', options: RouteOptions(hidden: true)); + final broadcast = route.broadcast(); final track = broadcast.publishTrack(name: 'events', info: null); - publication.announce(route: AnnounceRoute()); + route.announce(); final announced = (await announcement.timeout(timeout) as AnnounceEventPresent).announce; expect(announced.prefix, 'live'); @@ -383,6 +386,7 @@ void main() { track.finish(); broadcast.close(); broadcast.close(); // a second close is a no-op + route.dispose(); server.close(); }); @@ -526,8 +530,11 @@ void main() { test('a broadcast is reachable only while announced', () async { final origin = MoqOriginProducer(config: MoqOriginConfig()); - final publication = origin.createBroadcast(path: 'live'); - final broadcast = publication.broadcast(); + final route = origin.route( + path: 'live', + options: RouteOptions(hidden: true), + ); + final broadcast = route.broadcast(); broadcast.publishTrack(name: 'events', info: null); final consumer = origin.consume(); await expectLater( @@ -535,13 +542,14 @@ void main() { throwsA(anything), ); - publication.announce(route: AnnounceRoute()); + route.announce(); final announced = consumer.announced(config: MoqAnnounceConfig()); final first = await nextRoute(announced); expect(first, isA()); expect((first as AnnounceEventPresent).announce.prefix, 'live'); + expect(first.announce.route.instance, route.instanceId()); - publication.unannounce(); + route.withdraw(); final retracted = await nextRoute(announced); expect(retracted, isA()); expect((retracted as AnnounceEventAbsent).announce.prefix, 'live'); @@ -550,60 +558,90 @@ void main() { throwsA(anything), ); - publication.announce(route: AnnounceRoute()); - expect(await nextRoute(announced), isA()); + // Announcing again continues the same stream. + route.announce(); + final again = await nextRoute(announced) as AnnounceEventPresent; + expect(again.announce.route.instance, route.instanceId()); await consumer.request(path: 'live').timeout(timeout); - // Disposing the publication keeps the route; closing the broadcast ends it. - publication.dispose(); + // Disposing the broadcast handle keeps the route; cancelling the route retracts it, + // and its broadcast lives on. + broadcast.dispose(); await consumer.request(path: 'live').timeout(timeout); - broadcast.close(); + final kept = route.broadcast(); + route.cancel(); + expect(await nextRoute(announced), isA()); + expect(() => route.announce(), throwsA(isA())); + kept.publishTrack(name: 'after', info: null); + kept.close(); + route.dispose(); + announced.cancel(); + announced.dispose(); + }); + + test('closing the broadcast retracts its route', () async { + final origin = MoqOriginProducer(config: MoqOriginConfig()); + final announced = origin.consume().announced(config: MoqAnnounceConfig()); + final route = origin.route(path: 'live', options: RouteOptions()); + expect(await nextRoute(announced), isA()); + route.broadcast().close(); expect(await nextRoute(announced), isA()); + expect(() => route.announce(), throwsA(isA())); + route.dispose(); announced.cancel(); announced.dispose(); }); - test('a stale publication leaves its replacement alone', () async { + test('a closed route leaves its replacement alone', () async { final origin = MoqOriginProducer(config: MoqOriginConfig()); - final stale = origin.createBroadcast(path: 'live'); - stale.announce(route: AnnounceRoute()); + final stale = origin.route(path: 'live', options: RouteOptions()); stale.broadcast().close(); - final replacement = origin.createBroadcast(path: 'live'); - replacement.announce(route: AnnounceRoute()); - expect( - () => stale.announce(route: AnnounceRoute()), - throwsA(isA()), - ); - expect(() => stale.unannounce(), throwsA(isA())); + final replacement = origin.route(path: 'live', options: RouteOptions()); + expect(() => stale.announce(), throwsA(isA())); + expect(() => stale.setCost(cost: 1), throwsA(isA())); + stale.withdraw(); await origin.consume().request(path: 'live').timeout(timeout); replacement.broadcast().close(); + stale.dispose(); + replacement.dispose(); }); - test('a new instance restarts followers but stays listed', () async { + test('a new route restarts followers but stays listed', () async { final origin = MoqOriginProducer(config: MoqOriginConfig()); final consumer = origin.consume(); final announced = consumer.announced(config: MoqAnnounceConfig()); final following = consumer.follow(path: 'instance'); - final publication = origin.createBroadcast(path: 'instance'); + final first = origin.route(path: 'instance', options: RouteOptions()); - publication.announce(route: AnnounceRoute()); final present = await nextRoute(announced) as AnnounceEventPresent; - expect(present.announce.route.instance, isNotEmpty); + expect(present.announce.route.instance, first.instanceId()); (await following.available().timeout(timeout))!.dispose(); - publication.announce(route: AnnounceRoute(instance: 'camera', epoch: 1)); + final second = origin.route( + path: 'instance', + options: RouteOptions(instance: 'camera', epoch: 1), + ); + expect(second.instanceId(), 'camera'); (await following.available().timeout(timeout))!.dispose(); // The takeover was not listed, so the next event is the path going absent. - publication.unannounce(); + first.withdraw(); + second.withdraw(); final absent = await nextRoute(announced) as AnnounceEventAbsent; expect(absent.announce.route.instance, 'camera'); expect( - () => publication.announce(route: AnnounceRoute(instance: '')), + () => origin.route( + path: 'refused', + options: RouteOptions(instance: ''), + ), throwsA(isA()), ); + first.cancel(); + second.cancel(); + first.dispose(); + second.dispose(); following.cancel(); following.dispose(); announced.cancel(); @@ -615,17 +653,17 @@ void main() { () async { final origin = MoqOriginProducer(config: MoqOriginConfig()); final following = origin.consume().follow(path: 'offline'); - final publication = origin.createBroadcast(path: 'offline'); - - publication.announce(route: AnnounceRoute()); + final route = origin.route(path: 'offline', options: RouteOptions()); (await following.available().timeout(timeout))!.dispose(); - publication.unannounce(); + route.withdraw(); expect(await following.available().timeout(timeout), isNull); - publication.announce(route: AnnounceRoute()); + route.announce(); (await following.available().timeout(timeout))!.dispose(); + route.cancel(); + route.dispose(); following.cancel(); following.dispose(); }, @@ -636,27 +674,37 @@ void main() { final announced = origin.consume().announced( config: MoqAnnounceConfig(prefix: 'room', filter: '*/chat'), ); - final publication = origin.createBroadcast(path: 'room/alice/chat'); - publication.announce(route: AnnounceRoute()); + final route = origin.route( + path: 'room/alice/chat', + options: RouteOptions(), + ); final update = await nextRoute(announced) as AnnounceEventPresent; expect(update.announce.prefix, 'room/alice/chat'); expect(update.announce.captures, ['alice']); + route.dispose(); }); test('dynamic serves a request under a prefix', () async { final origin = MoqOriginProducer(config: MoqOriginConfig()); - final dynamic = origin.requests(prefix: 'live'); + final dynamic = origin.routePrefix(prefix: 'live', options: RouteOptions()); final pending = origin.consume().request(path: 'live/cam'); - final request = await dynamic.requestedBroadcast().timeout(timeout); + final request = (await dynamic.requested().timeout(timeout))!; expect(request.path(), 'live/cam'); - final prepared = request.prepare(); - final served = prepared.publish(); + // A hidden job route answers nobody until it announces. + final served = request.route(options: RouteOptions(hidden: true)); + expect(served.instanceId(), isNot(dynamic.instanceId())); + served.announce(); await pending.timeout(timeout); - // The publication controls the prepared fill: closing that ends its announcement. - prepared.broadcast().close(); - expect(() => served.unannounce(), throwsA(isA())); + // Closing the job's broadcast ends its route. + served.broadcast().close(); + expect(() => served.announce(), throwsA(isA())); + expect(() => dynamic.broadcast(), throwsA(isA())); dynamic.cancel(); + await expectLater( + dynamic.requested(), + throwsA(isA()), + ); dynamic.dispose(); served.dispose(); }); diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 65f0f46f21a..8dd3c33eb30 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -2813,7 +2813,7 @@ class FfiConverterMoqVideoProperties { class MoqAnnounce { final String prefix; final List captures; - final MoqRoute route; + final MoqRouteInfo route; MoqAnnounce({ required this.prefix, required this.captures, @@ -2838,7 +2838,7 @@ class FfiConverterMoqAnnounce { ); final captures = captures_lifted.value; new_offset += captures_lifted.bytesRead; - final route_lifted = FfiConverterMoqRoute.read( + final route_lifted = FfiConverterMoqRouteInfo.read( Uint8List.view(buf.buffer, new_offset), ); final route = route_lifted.value; @@ -2853,7 +2853,7 @@ class FfiConverterMoqAnnounce { final total_length = FfiConverterString.allocationSize(value.prefix) + FfiConverterSequenceString.allocationSize(value.captures) + - FfiConverterMoqRoute.allocationSize(value.route) + + FfiConverterMoqRouteInfo.allocationSize(value.route) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -2870,7 +2870,7 @@ class FfiConverterMoqAnnounce { value.captures, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterMoqRoute.write( + new_offset += FfiConverterMoqRouteInfo.write( value.route, Uint8List.view(buf.buffer, new_offset), ); @@ -2880,7 +2880,7 @@ class FfiConverterMoqAnnounce { static int allocationSize(MoqAnnounce value) { return FfiConverterString.allocationSize(value.prefix) + FfiConverterSequenceString.allocationSize(value.captures) + - FfiConverterMoqRoute.allocationSize(value.route) + + FfiConverterMoqRouteInfo.allocationSize(value.route) + 0; } } @@ -2960,77 +2960,6 @@ class FfiConverterMoqAnnounceConfig { } } -class MoqAnnounceRoute { - final int cost; - final String? instance; - final int epoch; - MoqAnnounceRoute({this.cost = 0, this.instance = null, this.epoch = 0}); -} - -class FfiConverterMoqAnnounceRoute { - static MoqAnnounceRoute lift(RustBuffer buf) { - return FfiConverterMoqAnnounceRoute.read(buf.asUint8List()).value; - } - - static LiftRetVal read(Uint8List buf) { - int new_offset = buf.offsetInBytes; - final cost_lifted = FfiConverterUInt64.read( - Uint8List.view(buf.buffer, new_offset), - ); - final cost = cost_lifted.value; - new_offset += cost_lifted.bytesRead; - final instance_lifted = FfiConverterOptionalString.read( - Uint8List.view(buf.buffer, new_offset), - ); - final instance = instance_lifted.value; - new_offset += instance_lifted.bytesRead; - final epoch_lifted = FfiConverterUInt64.read( - Uint8List.view(buf.buffer, new_offset), - ); - final epoch = epoch_lifted.value; - new_offset += epoch_lifted.bytesRead; - return LiftRetVal( - MoqAnnounceRoute(cost: cost, instance: instance, epoch: epoch), - new_offset - buf.offsetInBytes, - ); - } - - static RustBuffer lower(MoqAnnounceRoute value) { - final total_length = - FfiConverterUInt64.allocationSize(value.cost) + - FfiConverterOptionalString.allocationSize(value.instance) + - FfiConverterUInt64.allocationSize(value.epoch) + - 0; - final buf = Uint8List(total_length); - write(value, buf); - return toRustBuffer(buf); - } - - static int write(MoqAnnounceRoute value, Uint8List buf) { - int new_offset = buf.offsetInBytes; - new_offset += FfiConverterUInt64.write( - value.cost, - Uint8List.view(buf.buffer, new_offset), - ); - new_offset += FfiConverterOptionalString.write( - value.instance, - Uint8List.view(buf.buffer, new_offset), - ); - new_offset += FfiConverterUInt64.write( - value.epoch, - Uint8List.view(buf.buffer, new_offset), - ); - return new_offset - buf.offsetInBytes; - } - - static int allocationSize(MoqAnnounceRoute value) { - return FfiConverterUInt64.allocationSize(value.cost) + - FfiConverterOptionalString.allocationSize(value.instance) + - FfiConverterUInt64.allocationSize(value.epoch) + - 0; - } -} - class MoqOriginConfig { final int? cacheCapacityBytes; MoqOriginConfig({this.cacheCapacityBytes = null}); @@ -3077,12 +3006,12 @@ class FfiConverterMoqOriginConfig { } } -class MoqRoute { +class MoqRouteInfo { final List hops; final int cost; final bool anonymous; final String instance; - MoqRoute({ + MoqRouteInfo({ required this.hops, required this.cost, required this.anonymous, @@ -3090,12 +3019,12 @@ class MoqRoute { }); } -class FfiConverterMoqRoute { - static MoqRoute lift(RustBuffer buf) { - return FfiConverterMoqRoute.read(buf.asUint8List()).value; +class FfiConverterMoqRouteInfo { + static MoqRouteInfo lift(RustBuffer buf) { + return FfiConverterMoqRouteInfo.read(buf.asUint8List()).value; } - static LiftRetVal read(Uint8List buf) { + static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; final hops_lifted = FfiConverterSequenceUInt64.read( Uint8List.view(buf.buffer, new_offset), @@ -3118,7 +3047,7 @@ class FfiConverterMoqRoute { final instance = instance_lifted.value; new_offset += instance_lifted.bytesRead; return LiftRetVal( - MoqRoute( + MoqRouteInfo( hops: hops, cost: cost, anonymous: anonymous, @@ -3128,7 +3057,7 @@ class FfiConverterMoqRoute { ); } - static RustBuffer lower(MoqRoute value) { + static RustBuffer lower(MoqRouteInfo value) { final total_length = FfiConverterSequenceUInt64.allocationSize(value.hops) + FfiConverterUInt64.allocationSize(value.cost) + @@ -3140,7 +3069,7 @@ class FfiConverterMoqRoute { return toRustBuffer(buf); } - static int write(MoqRoute value, Uint8List buf) { + static int write(MoqRouteInfo value, Uint8List buf) { int new_offset = buf.offsetInBytes; new_offset += FfiConverterSequenceUInt64.write( value.hops, @@ -3161,7 +3090,7 @@ class FfiConverterMoqRoute { return new_offset - buf.offsetInBytes; } - static int allocationSize(MoqRoute value) { + static int allocationSize(MoqRouteInfo value) { return FfiConverterSequenceUInt64.allocationSize(value.hops) + FfiConverterUInt64.allocationSize(value.cost) + FfiConverterBool.allocationSize(value.anonymous) + @@ -3170,6 +3099,99 @@ class FfiConverterMoqRoute { } } +class MoqRouteOptions { + final bool hidden; + final int cost; + final String? instance; + final int epoch; + MoqRouteOptions({ + this.hidden = false, + this.cost = 0, + this.instance = null, + this.epoch = 0, + }); +} + +class FfiConverterMoqRouteOptions { + static MoqRouteOptions lift(RustBuffer buf) { + return FfiConverterMoqRouteOptions.read(buf.asUint8List()).value; + } + + static LiftRetVal read(Uint8List buf) { + int new_offset = buf.offsetInBytes; + final hidden_lifted = FfiConverterBool.read( + Uint8List.view(buf.buffer, new_offset), + ); + final hidden = hidden_lifted.value; + new_offset += hidden_lifted.bytesRead; + final cost_lifted = FfiConverterUInt64.read( + Uint8List.view(buf.buffer, new_offset), + ); + final cost = cost_lifted.value; + new_offset += cost_lifted.bytesRead; + final instance_lifted = FfiConverterOptionalString.read( + Uint8List.view(buf.buffer, new_offset), + ); + final instance = instance_lifted.value; + new_offset += instance_lifted.bytesRead; + final epoch_lifted = FfiConverterUInt64.read( + Uint8List.view(buf.buffer, new_offset), + ); + final epoch = epoch_lifted.value; + new_offset += epoch_lifted.bytesRead; + return LiftRetVal( + MoqRouteOptions( + hidden: hidden, + cost: cost, + instance: instance, + epoch: epoch, + ), + new_offset - buf.offsetInBytes, + ); + } + + static RustBuffer lower(MoqRouteOptions value) { + final total_length = + FfiConverterBool.allocationSize(value.hidden) + + FfiConverterUInt64.allocationSize(value.cost) + + FfiConverterOptionalString.allocationSize(value.instance) + + FfiConverterUInt64.allocationSize(value.epoch) + + 0; + final buf = Uint8List(total_length); + write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqRouteOptions value, Uint8List buf) { + int new_offset = buf.offsetInBytes; + new_offset += FfiConverterBool.write( + value.hidden, + Uint8List.view(buf.buffer, new_offset), + ); + new_offset += FfiConverterUInt64.write( + value.cost, + Uint8List.view(buf.buffer, new_offset), + ); + new_offset += FfiConverterOptionalString.write( + value.instance, + Uint8List.view(buf.buffer, new_offset), + ); + new_offset += FfiConverterUInt64.write( + value.epoch, + Uint8List.view(buf.buffer, new_offset), + ); + return new_offset - buf.offsetInBytes; + } + + static int allocationSize(MoqRouteOptions value) { + return FfiConverterBool.allocationSize(value.hidden) + + FfiConverterUInt64.allocationSize(value.cost) + + FfiConverterOptionalString.allocationSize(value.instance) + + FfiConverterUInt64.allocationSize(value.epoch) + + 0; + } +} + class MoqPosition { final int group; final int frame; @@ -13225,103 +13247,10 @@ class FfiConverterMoqAnnounceConsumer { } } -abstract class MoqBroadcastPreparedInterface { - MoqBroadcastProducer broadcast(); - MoqPublication publish(); -} - -final _MoqBroadcastPreparedFinalizer = Finalizer>((ptr) { - rustCall( - (status) => uniffi_moq_ffi_fn_free_moqbroadcastprepared(ptr, status), - ); -}); - -class MoqBroadcastPrepared implements MoqBroadcastPreparedInterface { - late final Pointer _ptr; - bool _isDisposed = false; - MoqBroadcastPrepared._(this._ptr) { - _MoqBroadcastPreparedFinalizer.attach(this, _ptr, detach: this); - } - factory MoqBroadcastPrepared.lift(Pointer ptr) { - return MoqBroadcastPrepared._(ptr); - } - Pointer uniffiClonePointer() { - if (_isDisposed) { - throw StateError("Object has already been disposed"); - } - return rustCall( - (status) => uniffi_moq_ffi_fn_clone_moqbroadcastprepared(_ptr, status), - ); - } - - void dispose() { - if (_isDisposed) { - return; - } - final status = calloc(); - _isDisposed = true; - _MoqBroadcastPreparedFinalizer.detach(this); - try { - uniffi_moq_ffi_fn_free_moqbroadcastprepared(_ptr, status); - checkCallStatus(NullRustCallStatusErrorHandler(), status); - } finally { - calloc.free(status); - } - } - - MoqBroadcastProducer broadcast() { - return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqbroadcastprepared_broadcast( - uniffiClonePointer(), - status, - ), - FfiConverterMoqBroadcastProducer.lift, - null, - ); - } - - MoqPublication publish() { - return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqbroadcastprepared_publish( - uniffiClonePointer(), - status, - ), - FfiConverterMoqPublication.lift, - moqExceptionErrorHandler, - ); - } -} - -class FfiConverterMoqBroadcastPrepared { - static MoqBroadcastPrepared lift(Pointer ptr) { - return MoqBroadcastPrepared.lift(ptr); - } - - static Pointer lower(MoqBroadcastPrepared value) { - return value.uniffiClonePointer(); - } - - static int allocationSize(MoqBroadcastPrepared value) { - return 8; - } - - static LiftRetVal read(Uint8List buf) { - final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); - final pointer = Pointer.fromAddress(handle); - return LiftRetVal(MoqBroadcastPrepared.lift(pointer), 8); - } - - static int write(MoqBroadcastPrepared value, Uint8List buf) { - final handle = lower(value); - buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); - return 8; - } -} - abstract class MoqBroadcastRequestInterface { String path(); - MoqBroadcastPrepared prepare(); void reject({required int errorCode}); + MoqRoute route({required MoqRouteOptions options}); void serve({required MoqBroadcastConsumer broadcast}); } @@ -13373,17 +13302,6 @@ class MoqBroadcastRequest implements MoqBroadcastRequestInterface { ); } - MoqBroadcastPrepared prepare() { - return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqbroadcastrequest_prepare( - uniffiClonePointer(), - status, - ), - FfiConverterMoqBroadcastPrepared.lift, - moqExceptionErrorHandler, - ); - } - void reject({required int errorCode}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqbroadcastrequest_reject( @@ -13394,6 +13312,18 @@ class MoqBroadcastRequest implements MoqBroadcastRequestInterface { }, moqExceptionErrorHandler); } + MoqRoute route({required MoqRouteOptions options}) { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqbroadcastrequest_route( + uniffiClonePointer(), + FfiConverterMoqRouteOptions.lower(options), + status, + ), + FfiConverterMoqRoute.lift, + moqExceptionErrorHandler, + ); + } + void serve({required MoqBroadcastConsumer broadcast}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqbroadcastrequest_serve( @@ -13642,8 +13572,11 @@ class FfiConverterMoqOriginConsumer { abstract class MoqOriginProducerInterface { MoqOriginConsumer consume(); - MoqPublication createBroadcast({required String path}); - MoqOriginRequests requests({required String prefix}); + MoqRoute route({required String path, required MoqRouteOptions options}); + MoqRoute routePrefix({ + required String prefix, + required MoqRouteOptions options, + }); } final _MoqOriginProducerFinalizer = Finalizer>((ptr) { @@ -13704,26 +13637,31 @@ class MoqOriginProducer implements MoqOriginProducerInterface { ); } - MoqPublication createBroadcast({required String path}) { + MoqRoute route({required String path, required MoqRouteOptions options}) { return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqoriginproducer_create_broadcast( + (status) => uniffi_moq_ffi_fn_method_moqoriginproducer_route( uniffiClonePointer(), FfiConverterString.lower(path), + FfiConverterMoqRouteOptions.lower(options), status, ), - FfiConverterMoqPublication.lift, + FfiConverterMoqRoute.lift, moqExceptionErrorHandler, ); } - MoqOriginRequests requests({required String prefix}) { + MoqRoute routePrefix({ + required String prefix, + required MoqRouteOptions options, + }) { return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqoriginproducer_requests( + (status) => uniffi_moq_ffi_fn_method_moqoriginproducer_route_prefix( uniffiClonePointer(), FfiConverterString.lower(prefix), + FfiConverterMoqRouteOptions.lower(options), status, ), - FfiConverterMoqOriginRequests.lift, + FfiConverterMoqRoute.lift, moqExceptionErrorHandler, ); } @@ -13755,31 +13693,34 @@ class FfiConverterMoqOriginProducer { } } -abstract class MoqOriginRequestsInterface { +abstract class MoqRouteInterface { + void announce(); + MoqBroadcastProducer broadcast(); void cancel(); - UniffiRustFuture requestedBroadcast(); + String instanceId(); + UniffiRustFuture requested(); + void setCost({required int cost}); + void withdraw(); } -final _MoqOriginRequestsFinalizer = Finalizer>((ptr) { - rustCall((status) => uniffi_moq_ffi_fn_free_moqoriginrequests(ptr, status)); +final _MoqRouteFinalizer = Finalizer>((ptr) { + rustCall((status) => uniffi_moq_ffi_fn_free_moqroute(ptr, status)); }); -class MoqOriginRequests implements MoqOriginRequestsInterface { +class MoqRoute implements MoqRouteInterface { late final Pointer _ptr; bool _isDisposed = false; - MoqOriginRequests._(this._ptr) { - _MoqOriginRequestsFinalizer.attach(this, _ptr, detach: this); + MoqRoute._(this._ptr) { + _MoqRouteFinalizer.attach(this, _ptr, detach: this); } - factory MoqOriginRequests.lift(Pointer ptr) { - return MoqOriginRequests._(ptr); + factory MoqRoute.lift(Pointer ptr) { + return MoqRoute._(ptr); } Pointer uniffiClonePointer() { if (_isDisposed) { throw StateError("Object has already been disposed"); } - return rustCall( - (status) => uniffi_moq_ffi_fn_clone_moqoriginrequests(_ptr, status), - ); + return rustCall((status) => uniffi_moq_ffi_fn_clone_moqroute(_ptr, status)); } void dispose() { @@ -13788,160 +13729,98 @@ class MoqOriginRequests implements MoqOriginRequestsInterface { } final status = calloc(); _isDisposed = true; - _MoqOriginRequestsFinalizer.detach(this); + _MoqRouteFinalizer.detach(this); try { - uniffi_moq_ffi_fn_free_moqoriginrequests(_ptr, status); + uniffi_moq_ffi_fn_free_moqroute(_ptr, status); checkCallStatus(NullRustCallStatusErrorHandler(), status); } finally { calloc.free(status); } } - void cancel() { + void announce() { return rustCall((status) { - uniffi_moq_ffi_fn_method_moqoriginrequests_cancel( - uniffiClonePointer(), - status, - ); - }, null); + uniffi_moq_ffi_fn_method_moqroute_announce(uniffiClonePointer(), status); + }, moqExceptionErrorHandler); } - UniffiRustFuture requestedBroadcast() { - return uniffiRustCallAsync( - () => uniffi_moq_ffi_fn_method_moqoriginrequests_requested_broadcast( + MoqBroadcastProducer broadcast() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqroute_broadcast( uniffiClonePointer(), + status, ), - ffi_moq_ffi_rust_future_poll_u64, - ffi_moq_ffi_rust_future_complete_u64, - ffi_moq_ffi_rust_future_cancel_u64, - ffi_moq_ffi_rust_future_free_u64, - (ptr) => - FfiConverterMoqBroadcastRequest.lift(Pointer.fromAddress(ptr)), + FfiConverterMoqBroadcastProducer.lift, moqExceptionErrorHandler, ); } -} - -class FfiConverterMoqOriginRequests { - static MoqOriginRequests lift(Pointer ptr) { - return MoqOriginRequests.lift(ptr); - } - - static Pointer lower(MoqOriginRequests value) { - return value.uniffiClonePointer(); - } - - static int allocationSize(MoqOriginRequests value) { - return 8; - } - - static LiftRetVal read(Uint8List buf) { - final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); - final pointer = Pointer.fromAddress(handle); - return LiftRetVal(MoqOriginRequests.lift(pointer), 8); - } - - static int write(MoqOriginRequests value, Uint8List buf) { - final handle = lower(value); - buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); - return 8; - } -} - -abstract class MoqPublicationInterface { - void announce({required MoqAnnounceRoute route}); - MoqBroadcastProducer broadcast(); - void unannounce(); -} - -final _MoqPublicationFinalizer = Finalizer>((ptr) { - rustCall((status) => uniffi_moq_ffi_fn_free_moqpublication(ptr, status)); -}); - -class MoqPublication implements MoqPublicationInterface { - late final Pointer _ptr; - bool _isDisposed = false; - MoqPublication._(this._ptr) { - _MoqPublicationFinalizer.attach(this, _ptr, detach: this); - } - factory MoqPublication.lift(Pointer ptr) { - return MoqPublication._(ptr); - } - Pointer uniffiClonePointer() { - if (_isDisposed) { - throw StateError("Object has already been disposed"); - } - return rustCall( - (status) => uniffi_moq_ffi_fn_clone_moqpublication(_ptr, status), - ); - } - - void dispose() { - if (_isDisposed) { - return; - } - final status = calloc(); - _isDisposed = true; - _MoqPublicationFinalizer.detach(this); - try { - uniffi_moq_ffi_fn_free_moqpublication(_ptr, status); - checkCallStatus(NullRustCallStatusErrorHandler(), status); - } finally { - calloc.free(status); - } - } - void announce({required MoqAnnounceRoute route}) { + void cancel() { return rustCall((status) { - uniffi_moq_ffi_fn_method_moqpublication_announce( - uniffiClonePointer(), - FfiConverterMoqAnnounceRoute.lower(route), - status, - ); - }, moqExceptionErrorHandler); + uniffi_moq_ffi_fn_method_moqroute_cancel(uniffiClonePointer(), status); + }, null); } - MoqBroadcastProducer broadcast() { + String instanceId() { return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqpublication_broadcast( + (status) => uniffi_moq_ffi_fn_method_moqroute_instance_id( uniffiClonePointer(), status, ), - FfiConverterMoqBroadcastProducer.lift, + FfiConverterString.lift, null, ); } - void unannounce() { + UniffiRustFuture requested() { + return uniffiRustCallAsync( + () => uniffi_moq_ffi_fn_method_moqroute_requested(uniffiClonePointer()), + ffi_moq_ffi_rust_future_poll_rust_buffer, + ffi_moq_ffi_rust_future_complete_rust_buffer, + ffi_moq_ffi_rust_future_cancel_rust_buffer, + ffi_moq_ffi_rust_future_free_rust_buffer, + FfiConverterOptionalMoqBroadcastRequest.lift, + moqExceptionErrorHandler, + ); + } + + void setCost({required int cost}) { return rustCall((status) { - uniffi_moq_ffi_fn_method_moqpublication_unannounce( + uniffi_moq_ffi_fn_method_moqroute_set_cost( uniffiClonePointer(), + FfiConverterUInt64.lower(cost), status, ); }, moqExceptionErrorHandler); } + + void withdraw() { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqroute_withdraw(uniffiClonePointer(), status); + }, moqExceptionErrorHandler); + } } -class FfiConverterMoqPublication { - static MoqPublication lift(Pointer ptr) { - return MoqPublication.lift(ptr); +class FfiConverterMoqRoute { + static MoqRoute lift(Pointer ptr) { + return MoqRoute.lift(ptr); } - static Pointer lower(MoqPublication value) { + static Pointer lower(MoqRoute value) { return value.uniffiClonePointer(); } - static int allocationSize(MoqPublication value) { + static int allocationSize(MoqRoute value) { return 8; } - static LiftRetVal read(Uint8List buf) { + static LiftRetVal read(Uint8List buf) { final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); final pointer = Pointer.fromAddress(handle); - return LiftRetVal(MoqPublication.lift(pointer), 8); + return LiftRetVal(MoqRoute.lift(pointer), 8); } - static int write(MoqPublication value, Uint8List buf) { + static int write(MoqRoute value, Uint8List buf) { final handle = lower(value); buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); return 8; @@ -16958,6 +16837,55 @@ class FfiConverterOptionalMoqBroadcastConsumer { } } +class FfiConverterOptionalMoqBroadcastRequest { + static MoqBroadcastRequest? lift(RustBuffer buf) { + return FfiConverterOptionalMoqBroadcastRequest.read( + buf.asUint8List(), + ).value; + } + + static LiftRetVal read(Uint8List buf) { + if (ByteData.view(buf.buffer, buf.offsetInBytes).getInt8(0) == 0) { + return LiftRetVal(null, 1); + } + final result = FfiConverterMoqBroadcastRequest.read( + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ); + return LiftRetVal(result.value, result.bytesRead + 1); + } + + static int allocationSize([MoqBroadcastRequest? value]) { + if (value == null) { + return 1; + } + return FfiConverterMoqBroadcastRequest.allocationSize(value) + 1; + } + + static RustBuffer lower(MoqBroadcastRequest? value) { + if (value == null) { + return toRustBuffer(Uint8List.fromList([0])); + } + final buf = Uint8List( + FfiConverterOptionalMoqBroadcastRequest.allocationSize(value), + ); + FfiConverterOptionalMoqBroadcastRequest.write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqBroadcastRequest? value, Uint8List buf) { + if (value == null) { + buf[0] = 0; + return 1; + } + buf[0] = 1; + return FfiConverterMoqBroadcastRequest.write( + value, + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ) + + 1; + } +} + class FfiConverterOptionalMoqCatalog { static MoqCatalog? lift(RustBuffer buf) { return FfiConverterOptionalMoqCatalog.read(buf.asUint8List()).value; @@ -20803,38 +20731,6 @@ external Pointer uniffi_moq_ffi_fn_method_moqannounceconsumer_next( Pointer ptr, ); -@Native Function(Pointer, Pointer)>( - assetId: _uniffiAssetId, -) -external Pointer uniffi_moq_ffi_fn_clone_moqbroadcastprepared( - Pointer handle, - Pointer uniffiStatus, -); - -@Native, Pointer)>( - assetId: _uniffiAssetId, -) -external void uniffi_moq_ffi_fn_free_moqbroadcastprepared( - Pointer handle, - Pointer uniffiStatus, -); - -@Native Function(Pointer, Pointer)>( - assetId: _uniffiAssetId, -) -external Pointer uniffi_moq_ffi_fn_method_moqbroadcastprepared_broadcast( - Pointer ptr, - Pointer uniffiStatus, -); - -@Native Function(Pointer, Pointer)>( - assetId: _uniffiAssetId, -) -external Pointer uniffi_moq_ffi_fn_method_moqbroadcastprepared_publish( - Pointer ptr, - Pointer uniffiStatus, -); - @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -20859,20 +20755,21 @@ external RustBuffer uniffi_moq_ffi_fn_method_moqbroadcastrequest_path( Pointer uniffiStatus, ); -@Native Function(Pointer, Pointer)>( +@Native, Uint16, Pointer)>( assetId: _uniffiAssetId, ) -external Pointer uniffi_moq_ffi_fn_method_moqbroadcastrequest_prepare( +external void uniffi_moq_ffi_fn_method_moqbroadcastrequest_reject( Pointer ptr, + int error_code, Pointer uniffiStatus, ); -@Native, Uint16, Pointer)>( - assetId: _uniffiAssetId, -) -external void uniffi_moq_ffi_fn_method_moqbroadcastrequest_reject( +@Native< + Pointer Function(Pointer, RustBuffer, Pointer) +>(assetId: _uniffiAssetId) +external Pointer uniffi_moq_ffi_fn_method_moqbroadcastrequest_route( Pointer ptr, - int error_code, + RustBuffer options, Pointer uniffiStatus, ); @@ -20996,28 +20893,39 @@ external Pointer uniffi_moq_ffi_fn_method_moqoriginproducer_consume( ); @Native< - Pointer Function(Pointer, RustBuffer, Pointer) + Pointer Function( + Pointer, + RustBuffer, + RustBuffer, + Pointer, + ) >(assetId: _uniffiAssetId) -external Pointer -uniffi_moq_ffi_fn_method_moqoriginproducer_create_broadcast( +external Pointer uniffi_moq_ffi_fn_method_moqoriginproducer_route( Pointer ptr, RustBuffer path, + RustBuffer options, Pointer uniffiStatus, ); @Native< - Pointer Function(Pointer, RustBuffer, Pointer) + Pointer Function( + Pointer, + RustBuffer, + RustBuffer, + Pointer, + ) >(assetId: _uniffiAssetId) -external Pointer uniffi_moq_ffi_fn_method_moqoriginproducer_requests( +external Pointer uniffi_moq_ffi_fn_method_moqoriginproducer_route_prefix( Pointer ptr, RustBuffer prefix, + RustBuffer options, Pointer uniffiStatus, ); @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) -external Pointer uniffi_moq_ffi_fn_clone_moqoriginrequests( +external Pointer uniffi_moq_ffi_fn_clone_moqroute( Pointer handle, Pointer uniffiStatus, ); @@ -21025,7 +20933,7 @@ external Pointer uniffi_moq_ffi_fn_clone_moqoriginrequests( @Native, Pointer)>( assetId: _uniffiAssetId, ) -external void uniffi_moq_ffi_fn_free_moqoriginrequests( +external void uniffi_moq_ffi_fn_free_moqroute( Pointer handle, Pointer uniffiStatus, ); @@ -21033,54 +20941,53 @@ external void uniffi_moq_ffi_fn_free_moqoriginrequests( @Native, Pointer)>( assetId: _uniffiAssetId, ) -external void uniffi_moq_ffi_fn_method_moqoriginrequests_cancel( +external void uniffi_moq_ffi_fn_method_moqroute_announce( Pointer ptr, Pointer uniffiStatus, ); -@Native Function(Pointer)>(assetId: _uniffiAssetId) -external Pointer -uniffi_moq_ffi_fn_method_moqoriginrequests_requested_broadcast( - Pointer ptr, -); - @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) -external Pointer uniffi_moq_ffi_fn_clone_moqpublication( - Pointer handle, +external Pointer uniffi_moq_ffi_fn_method_moqroute_broadcast( + Pointer ptr, Pointer uniffiStatus, ); @Native, Pointer)>( assetId: _uniffiAssetId, ) -external void uniffi_moq_ffi_fn_free_moqpublication( - Pointer handle, +external void uniffi_moq_ffi_fn_method_moqroute_cancel( + Pointer ptr, Pointer uniffiStatus, ); -@Native, RustBuffer, Pointer)>( +@Native, Pointer)>( assetId: _uniffiAssetId, ) -external void uniffi_moq_ffi_fn_method_moqpublication_announce( +external RustBuffer uniffi_moq_ffi_fn_method_moqroute_instance_id( Pointer ptr, - RustBuffer route, Pointer uniffiStatus, ); -@Native Function(Pointer, Pointer)>( +@Native Function(Pointer)>(assetId: _uniffiAssetId) +external Pointer uniffi_moq_ffi_fn_method_moqroute_requested( + Pointer ptr, +); + +@Native, Uint64, Pointer)>( assetId: _uniffiAssetId, ) -external Pointer uniffi_moq_ffi_fn_method_moqpublication_broadcast( +external void uniffi_moq_ffi_fn_method_moqroute_set_cost( Pointer ptr, + int cost, Pointer uniffiStatus, ); @Native, Pointer)>( assetId: _uniffiAssetId, ) -external void uniffi_moq_ffi_fn_method_moqpublication_unannounce( +external void uniffi_moq_ffi_fn_method_moqroute_withdraw( Pointer ptr, Pointer uniffiStatus, ); @@ -22835,20 +22742,14 @@ external int uniffi_moq_ffi_checksum_method_moqannounceconsumer_cancel(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqannounceconsumer_next(); -@Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqbroadcastprepared_broadcast(); - -@Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqbroadcastprepared_publish(); - @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_path(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_prepare(); +external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_reject(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_reject(); +external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_route(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_serve(); @@ -22872,27 +22773,31 @@ external int uniffi_moq_ffi_checksum_method_moqoriginconsumer_request(); external int uniffi_moq_ffi_checksum_method_moqoriginproducer_consume(); @Native(assetId: _uniffiAssetId) -external int -uniffi_moq_ffi_checksum_method_moqoriginproducer_create_broadcast(); +external int uniffi_moq_ffi_checksum_method_moqoriginproducer_route(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqoriginproducer_requests(); +external int uniffi_moq_ffi_checksum_method_moqoriginproducer_route_prefix(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqoriginrequests_cancel(); +external int uniffi_moq_ffi_checksum_method_moqroute_announce(); @Native(assetId: _uniffiAssetId) -external int -uniffi_moq_ffi_checksum_method_moqoriginrequests_requested_broadcast(); +external int uniffi_moq_ffi_checksum_method_moqroute_broadcast(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqpublication_announce(); +external int uniffi_moq_ffi_checksum_method_moqroute_cancel(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqpublication_broadcast(); +external int uniffi_moq_ffi_checksum_method_moqroute_instance_id(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqpublication_unannounce(); +external int uniffi_moq_ffi_checksum_method_moqroute_requested(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqroute_set_cost(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqroute_withdraw(); @Native(assetId: _uniffiAssetId) external int @@ -23648,23 +23553,16 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqannounceconsumer_next() != 38311) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqbroadcastprepared_broadcast() != - 42363) { - throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); - } - if (uniffi_moq_ffi_checksum_method_moqbroadcastprepared_publish() != 60136) { - throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); - } if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_path() != 6534) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_prepare() != 45877) { + if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_reject() != 9727) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_reject() != 9727) { + if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_route() != 16046) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_serve() != 16802) { + if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_serve() != 2580) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqfollowing_available() != 26337) { @@ -23685,27 +23583,31 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqoriginproducer_consume() != 52357) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqoriginproducer_create_broadcast() != - 43708) { + if (uniffi_moq_ffi_checksum_method_moqoriginproducer_route() != 27041) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqoriginproducer_route_prefix() != 3472) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqroute_announce() != 46977) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqoriginproducer_requests() != 8499) { + if (uniffi_moq_ffi_checksum_method_moqroute_broadcast() != 31588) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqoriginrequests_cancel() != 18954) { + if (uniffi_moq_ffi_checksum_method_moqroute_cancel() != 41411) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqoriginrequests_requested_broadcast() != - 47029) { + if (uniffi_moq_ffi_checksum_method_moqroute_instance_id() != 18728) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqpublication_announce() != 60624) { + if (uniffi_moq_ffi_checksum_method_moqroute_requested() != 49558) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqpublication_broadcast() != 38236) { + if (uniffi_moq_ffi_checksum_method_moqroute_set_cost() != 30911) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqpublication_unannounce() != 21154) { + if (uniffi_moq_ffi_checksum_method_moqroute_withdraw() != 4611) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqbroadcastproducer_create_datagrams() != @@ -24065,7 +23967,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_constructor_moqoriginproducer_new() != 48126) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_constructor_moqbroadcastproducer_new() != 12099) { + if (uniffi_moq_ffi_checksum_constructor_moqbroadcastproducer_new() != 2448) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqserver_new() != 49910) { diff --git a/dart/moq_ffi/test/future_test.dart b/dart/moq_ffi/test/future_test.dart index 92d8d311bdb..62e154c4ff9 100644 --- a/dart/moq_ffi/test/future_test.dart +++ b/dart/moq_ffi/test/future_test.dart @@ -137,12 +137,15 @@ void main() { await pending.cancel(); await error; final next = cursor.next(); - final publication = origin.createBroadcast(path: 'still-listening'); + final route = origin.route( + path: 'still-listening', + options: MoqRouteOptions(), + ); try { - publication.announce(route: MoqAnnounceRoute()); expect(await next, isA()); } finally { - publication.broadcast().close(); + route.broadcast().close(); + route.dispose(); } } finally { cursor.cancel(); diff --git a/demo/carla/sim/moq_carla_sim/main.py b/demo/carla/sim/moq_carla_sim/main.py index 91e2ce38fa1..88585fb09d0 100644 --- a/demo/carla/sim/moq_carla_sim/main.py +++ b/demo/carla/sim/moq_carla_sim/main.py @@ -241,11 +241,11 @@ async def run(args: argparse.Namespace) -> None: async with moq.connect(args.url) as client: try: for truck in world.trucks: - publication = client.create_broadcast(broadcast_path(truck.name, args.camera)) + route = client.route(broadcast_path(truck.name, args.camera), hidden=True) video = await bridge.open( - bridge_stream(truck.name, args.camera), renditions(camera), publication.broadcast + bridge_stream(truck.name, args.camera), renditions(camera), route.broadcast ) - session = TruckSession(truck, publication, video, args.location, map_name, world.clock) + session = TruckSession(truck, route, video, args.location, map_name, world.clock) sessions.append(session) log.info( "publishing %s, consuming %s/*", diff --git a/demo/carla/sim/moq_carla_sim/runtime.py b/demo/carla/sim/moq_carla_sim/runtime.py index 48c519fa27d..51aceae2e6b 100644 --- a/demo/carla/sim/moq_carla_sim/runtime.py +++ b/demo/carla/sim/moq_carla_sim/runtime.py @@ -93,19 +93,21 @@ class TruckSession: def __init__( self, truck: Truck, - publication: moq.Publication, + route: moq.Route, video: BridgeStream, location: str | None, map_name: str | None, clock: Clock, ) -> None: self._truck = truck + # Held for the session's lifetime: dropping the route retracts the broadcast. + self._route = route self._video = video self._clock = clock self._location = location self._map_name = map_name self._drive = Drive() - self._status = StatusPublisher(publication.broadcast) + self._status = StatusPublisher(route.broadcast) # Bounded: drivers are untrusted publishers, so an unbounded queue is a # memory-growth path under one that floods; a full queue instead blocks # that driver's own task. @@ -113,12 +115,12 @@ def __init__( self._media_pipeline: dict[str, list[dict[str, Any]]] = {} self._deadline: float | None = None self._stuck = StuckDetector() - # A broadcast starts unadvertised; the player discovers trucks by - # announcement, so advertise once the status and video tracks exist. - # The stream's are there already: opening it advertised them. The - # broadcast mints a fresh instance, so viewers see a restarted worker - # as a restart rather than a stalled broadcast. - publication.announce() + # The route starts hidden; the player discovers trucks by announcement, + # so advertise once the status and video tracks exist. The stream's are + # there already: opening it advertised them. The route mints a fresh + # instance, so viewers see a restarted worker as a restart rather than + # a stalled broadcast. + route.announce() def stop_video(self) -> None: """End the video tracks cleanly and stop the bridge encoding them.""" diff --git a/demo/carla/sim/tests/test_runtime.py b/demo/carla/sim/tests/test_runtime.py index 61a73a1e333..cfa4b76d015 100644 --- a/demo/carla/sim/tests/test_runtime.py +++ b/demo/carla/sim/tests/test_runtime.py @@ -534,10 +534,10 @@ def respawn() -> None: def test_session_announces_after_populating_tracks() -> None: - """The player lists trucks from announcements, and a broadcast starts - unadvertised, so a session that never announces is invisible.""" + """The player lists trucks from announcements, and the route starts hidden, + so a session that never announces is invisible.""" calls: list[object] = [] - publication = SimpleNamespace( + route = SimpleNamespace( broadcast=SimpleNamespace( publish_track=lambda name, info=None: calls.append(name) or SimpleNamespace(demand=SimpleNamespace) ), @@ -545,7 +545,7 @@ def test_session_announces_after_populating_tracks() -> None: ) # The video tracks were advertised when the bridge stream opened. - runtime.TruckSession(SimpleNamespace(name="truck1"), publication, SimpleNamespace(), None, None, FakeClock()) + runtime.TruckSession(SimpleNamespace(name="truck1"), route, SimpleNamespace(), None, None, FakeClock()) assert calls == ["status", "announce"] diff --git a/demo/carla/web/src/truck.ts b/demo/carla/web/src/truck.ts index e16c27b7eeb..cbba17bf2ce 100644 --- a/demo/carla/web/src/truck.ts +++ b/demo/carla/web/src/truck.ts @@ -414,8 +414,8 @@ export class Truck { const driverId = crypto.randomUUID().replaceAll("-", "").slice(0, 12); this.driverId.set(driverId); - const driverBroadcastPublication = conn.createBroadcast(driverPath(this.name, driverId)); - const driverBroadcast = driverBroadcastPublication.broadcast; + const driverBroadcastRoute = conn.route(driverPath(this.name, driverId), { hidden: true }); + const driverBroadcast = driverBroadcastRoute.broadcast; effect.cleanup(() => { driverBroadcast.close(); this.driverId.set(undefined); @@ -429,7 +429,7 @@ export class Truck { effect.run(this.#runControlTrack.bind(this, track, producer)); // A fresh instance per lease, which each publication mints: the truck binds its single // driver to this path and instance. - driverBroadcastPublication.announce(); + driverBroadcastRoute.announce(); } #runSafetyControl(connection: Moq.Connection, effect: Moq.Signals.Effect) { @@ -438,10 +438,10 @@ export class Truck { if (!conn || !command) return; const driverId = `safety-${crypto.randomUUID().replaceAll("-", "").slice(0, 12)}`; - const broadcastPublication = conn.createBroadcast(driverPath(this.name, driverId)); - const broadcast = broadcastPublication.broadcast; + const broadcastRoute = conn.route(driverPath(this.name, driverId), { hidden: true }); + const broadcast = broadcastRoute.broadcast; const safety = new SafetyCommandBroadcast(command, broadcast); - broadcastPublication.announce(); + broadcastRoute.announce(); effect.cleanup(() => safety.close()); } diff --git a/doc/bin/obs.md b/doc/bin/obs.md index d16f18be7cb..72fbabe86da 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -12,7 +12,7 @@ OBS Studio install. - **Subscribe**: add a "MoQ Source", enter the relay URL and broadcast path, and the stream appears in the scene. - **Dock**: a **MoQ** dock with Go Live, encoding that uses the OBS Output settings or custom settings for this stream only, and live stats (protocol, RTT, bandwidth, loss), and the reason while a stream connects or reconnects. -Each Start Streaming publishes under a fresh instance. The client's automatic +Each Start Streaming publishes under a fresh instance, which the dock shows. The client's automatic reconnects keep the same instance. A stop/start, or an OBS auto-reconnect after the client gives up, republishes the broadcast under a new instance, which viewers see as a new stream. diff --git a/doc/concept/identity.md b/doc/concept/identity.md index 681c50d54c4..5b2ac5021cb 100644 --- a/doc/concept/identity.md +++ b/doc/concept/identity.md @@ -173,26 +173,28 @@ already served, start a new prefix route. Its first subscription stays on the prefix route without a restart. A job that may restart independently, such as a transcoder claiming -`transcode`, instead prepares and publishes each requested path. A claim +`transcode`, instead creates each requested path's own exact route. A claim promises capability, not content. Each requested path is a separate job, announced at its exact path under a fresh instance of its own. ```rust -let claim = origin.requests("transcode")?; -while let Ok(request) = claim.requested_broadcast().await { +let claim = origin.route_prefix("transcode", RouteOptions::default())?; +while let Some(request) = claim.requested().await { // A fresh instance for this job, never one shared with another path or run. - let prepared = request.prepare()?; - let video = prepared.broadcast().create_track("video", info.clone())?; + // Hidden until its tracks exist. + let job = request.route(RouteOptions::hidden())?; + let video = job.broadcast().create_track("video", info.clone())?; // Announces the exact path under that instance and answers the waiting request. - let output = prepared.publish()?; - spawn(run_job(video, output)); + job.announce()?; + spawn(run_job(video, job)); } ``` -JavaScript mirrors this with `request.prepare()` and `prepared.publish()`; -see [`@moq/net`](/lib/js/net) and [`moq-net`](/lib/rs/moq-net). -A prepared answer is unannounced until published, and dropping it unpublished -refuses the request. +JavaScript mirrors this with `request.route({ hidden: true })` and +`job.announce()`; see [`@moq/net`](/lib/js/net) and [`moq-net`](/lib/rs/moq-net). +A hidden job route is unannounced until it announces, and dropping it before +then refuses the request. Ending a job's route withdraws only its path: the +prefix route keeps answering later requests. A lazy job's lifecycle, as a viewer of `transcode/alice` sees it through a relay: @@ -212,7 +214,7 @@ A lazy job's lifecycle, as a viewer of `transcode/alice` sees it through a relay second request reaches job A. 3. **Steady state.** Requests resolve instance A by its exact route. Routes carrying instance A through other relays fail over without a seam. -4. **Job restart.** The worker closes job A's publication. The path falls back +4. **Job restart.** The worker drops job A's route. The path falls back to the claim, the next request asks the worker again, and job B publishes under a fresh instance. Followers are handed each new broadcast; relays drop job A's cached groups, so a viewer returning within the cache window never diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 10ee8b867f6..9bd3e9c4f3f 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -68,27 +68,31 @@ if (session < 0) ```c const char *path = "my-stream.hang"; -uint32_t broadcast; -int publication = moq_origin_create_broadcast(origin, path, strlen(path), &broadcast); -if (publication < 0) +moq_route_options options; +memset(&options, 0, sizeof(options)); // zeroed means visible, cost 0, a fresh instance +options.hidden = true; // fill the catalog before anyone finds it +int route = moq_origin_route(origin, path, strlen(path), &options); +if (route < 0) return fail(moq_error()); -// Fill tracks on broadcast here; announce on the publication. - -moq_announce_route route; -memset(&route, 0, sizeof(route)); // zeroed means cost 0 and the minted instance -if (moq_publication_announce((uint32_t)publication, &route) < 0) +int broadcast = moq_route_broadcast((uint32_t)route); +// Fill tracks on broadcast here, then make the route visible. +if (moq_route_announce((uint32_t)route) < 0) return fail(moq_error()); ``` -A route carries only a cost and the stream's instance; relays add the hops. Each -publication mints a fresh instance and keeps it across re-announcing, so a restarted -publisher is a new stream that `moq_origin_follow` hands viewers instead of a stalled +The route keeps the broadcast announced: `moq_route_free()` retracts it, and +`moq_publish_close()` ends both. A route carries only a cost and the stream's instance; +relays add the hops. Each route mints a fresh instance (`moq_route_instance()`) and keeps it +across `moq_route_withdraw()` and `moq_route_announce()`, so a restarted publisher, being a +new route, is a new stream that `moq_origin_follow` hands viewers instead of a stalled broadcast; the path stays `MOQ_ANNOUNCE_KIND_PRESENT` throughout. The follow callback reports each instance as `MOQ_FOLLOW_EVENT_ONLINE` with its handle, `MOQ_FOLLOW_EVENT_OFFLINE` when the path goes offline, and one `MOQ_FOLLOW_EVENT_END`. Set `instance` only for a publisher that continues its group sequences across restarts, and raise `epoch` on each: readers stitch every route of one instance together, so restarting the sequences under an old instance splices unrelated groups into -their tracks. +their tracks. To serve paths on demand, `moq_origin_route_prefix()` delivers each request to +answer with `moq_broadcast_request_serve()`, `moq_broadcast_request_route()`, or +`moq_broadcast_request_reject()`. Raw video encoders take an exact numerator/denominator frame rate, such as 30000/1001. Publication track names stay separate from codec settings. For simulcast, give each rendition the next one down as the `lower` handle in its `moq_video_encode_options`: it stops encoding, advertised as disabled, while its bandwidth grant cannot fund it, and resumes once the grant recovers. A rung only disables while the session probes for bandwidth, which on native transports takes moq-quic with BBR3. For pre-encoded video, publish from the lowest rendition up and set `moq_video_init.lower` to the next lower media handle. Reserve each track with `moq_allocator_reserve_media`, then bind its reservation with `moq_rate_control_create` and call `moq_rate_control_update` on every frame. Apply changed targets to your encoder and `moq_publish_media_set_enabled`, resuming video on a keyframe; close the control and reservation separately when done. @@ -110,7 +114,7 @@ inside. The header is the reference: each function carries a doc comment. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `moq_publish_media_cut`: after every frame, or less often to batch frames into fewer groups. Pass that cadence as `moq_audio_init.hint.group_duration_us`. - **Catalog hints.** Give the catalog what the encoder knows instead of having it estimated: `moq_video_init.hint` (coded size, bitrate, frame rate, group duration) and `moq_audio_init.hint` (bitrate, group duration). A supplied bitrate is never re-estimated. `group_duration_us` is the longest span between two group starts: the GOP, or your cut cadence. Leave a field's `has_*` flag false to have it measured. A bitrate or `group_duration_us` flag set with a 0 value returns `MOQ_ERROR_INVALID_CONFIG`. - **Discovery.** Announcement captures are always a list of wildcard matches, empty when the filter has no wildcards. -- **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE` (an internal error over moq-transport, which has no such code), and its handle is released. Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). +- **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` or `moq_route_free()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE` (an internal error over moq-transport, which has no such code), and its handle is released. Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. - **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, NULL on an untimed track and valid as long as the payload. Stream tracks moq-c creates are timed, so their raw writes need one. Datagram tracks are separate and default to untimed; set their timescale when creating them to require timestamps. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any JSON write (snapshot update, stream append, window push or pop) fails with `MOQ_ERROR_INVALID_POINTER` and publishes nothing. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. - **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 62b42ad3d5e..f8fad94854b 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -137,8 +137,10 @@ A raw `moq::Frame` with `std::nullopt` is untimed. // Publish encoded frames, or raw pixels with the codec inside the binding. // session is connected as above; opus_init, packet, and rgba come from your // encoder or capture source. -auto publication = ok(session->publish()->create_broadcast("my-stream.hang")); -auto broadcast = publication->broadcast(); // fill tracks here; announce on the publication +moq::RouteOptions options; +options.hidden = true; // fill tracks before anyone finds it; hold the route to stay announced +auto route = ok(session->publish()->route("my-stream.hang", options)); +auto broadcast = ok(route->broadcast()); auto audio = ok(moq::MediaTrackProducer::audio(broadcast, moq::MediaTarget::kNamed{}, {moq::AudioFormat::kOpus, opus_init})); ok(audio->write_frame({packet, moq::Timestamp{960, 48'000}})); // 20 ms @@ -146,8 +148,8 @@ moq::VideoEncoderOutput output{moq::VideoCodec::kH264, std::nullopt, std::nullop auto catalog = ok(moq::MediaCatalogProducer::init(broadcast)); auto video = ok(moq::VideoProducer::init(catalog, {{moq::VideoPixelFormat::kRgba, 1280, 720, {30000, 1001}}, output, "camera", nullptr})); ok(video->write({{0, 30'000}, rgba})); -ok(publication->announce({})); // each broadcast mints a fresh instance -ok(broadcast->close()); // keep the producer alive while publishing, then close explicitly +ok(route->announce()); // each route mints a fresh instance, route->instance_id() +ok(broadcast->close()); // keep the producer alive while publishing, then close explicitly ``` Raw video encoders take an exact numerator/denominator frame rate, such as 30000/1001. Producer options hold input, codec settings, track naming, and optional session bandwidth ownership; standalone encoders take only codec settings. For simulcast, give each rendition the next one down as `lower`: it stops encoding, advertised as disabled, while its bandwidth grant cannot fund it, and resumes once the grant recovers. A rung only disables while the session probes for bandwidth, which on native transports takes moq-quic with BBR3. A pre-encoded video track takes `lower` in its `VideoInit` too, as a `moq::MediaProducer::kTrack` or `kStream`, which only places it one priority below; follow its reservation with `RateControl`, and while it reports disabled, drop the frames, call `set_enabled(false)` after a `discontinuity()`, and `set_enabled(true)` on the keyframe that resumes it. A `MediaTrackStreamProducer` finds its own frames: `set_enabled(false)` drops what is written to it, and after `set_enabled(true)` it resumes at the stream's next keyframe. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index c5df8857bf0..dff6b40a757 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -81,7 +81,8 @@ print(await catalog.next()); // Publish raw pixels; the binding encodes them. rgba and pts come from your capture source. import 'package:moq/video.dart' as video; -final camera = moq.createBroadcast('live/camera'); +// Hidden until announced, so the catalog is filled before anyone finds it. +final camera = moq.route('live/camera', options: RouteOptions(hidden: true)); final encoder = video.Producer( catalog: media.CatalogProducer(broadcast: camera.broadcast()), options: video.ProducerOptions( @@ -99,7 +100,7 @@ final encoder = video.Producer( ), ); encoder.write(frame: video.Frame(timestamp: pts, data: rgba)); -camera.announce(route: AnnounceRoute()); +camera.announce(); encoder.finish(); ``` @@ -126,15 +127,15 @@ if (read is video.ReadFrame) { ```dart // Publish already-encoded frames. bytes comes from your encoder or application source. -final publication = moq.createBroadcast('live/camera'); -final mine = publication.broadcast(); +final route = moq.route('live/camera'); // visible at once, under a fresh instance +print(route.instanceId()); +final mine = route.broadcast(); final track = mine.publishTrack(name: 'video', info: null); final group = track.appendGroup(); group.writeFrame(frame: Frame(payload: bytes, timestamp: null)); group.finish(); -publication.announce(route: AnnounceRoute()); // the broadcast mints its own instance track.finish(); -mine.close(); +mine.close(); // ends the route too await moq.close(); ``` @@ -147,13 +148,14 @@ The rest of the [shared feature list](/lib/#what-every-binding-can-do) maps one to one; the API reference has the names, and [Layers](/lib/layers) shows which module holds each. -- **Names.** Types drop the `Moq` prefix (`Session`, `BroadcastProducer`) as aliases, so the generated names still work. `Container`, `Route`, and the exceptions keep it, since Flutter owns those names. +- **Names.** Types drop the `Moq` prefix (`Session`, `BroadcastProducer`, `RouteOptions`) as aliases, so the generated names still work. `MoqContainer`, `MoqRoute`, and the exceptions keep it, since Flutter owns those names. +- **Routes.** `route(path)` publishes a broadcast and `routePrefix(prefix)` answers requests beneath a prefix, each returning a `MoqRoute`. Hold it: cancelling or disposing it retracts the route, while a broadcast handle alone does not keep it announced. It keeps its instance across `withdraw()` and `announce()`, so a new run is a new route. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or less often to batch frames into fewer groups. - **Timeline breaks.** On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. - **Media reads.** `media.TrackConsumer`, `audio.Consumer`, and `video.Consumer` return a `Read` in order: a `ReadFrame`, a `ReadGap` where media was lost, or a `ReadEnd` where the publisher stopped its encoder. A gap breaks continuity. An encoder end is not stream EOF: following frames before its endpoint are the old encoder's drain; the first at or past it starts fresh. A decoder reads everything the track still holds unless a live player sets `start: media.DecodeStart.latest` in its decoder output, which joins at the newest group and skips the cached backlog. - **Decoded frames hold decoder buffers.** `dispose()` each frame from a `video.Consumer` promptly rather than waiting for the garbage collector, or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`. - **Closing.** `await moq.close()` drains for up to one second and reports its result. `session.shutdown()` requests the drain synchronously; `await session.closed()` waits for its result. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Awaiting cancellation of an announcement, grant, or request subscription releases its pending native read. Announcements and grants also release their consumer; server listeners leave their shared server usable. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. -- **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline; disposing its `Publication` does not. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). +- **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` or disposing its `MoqRoute` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. - **Viewers.** `client.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps: ...)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps: ...)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `dispose()` it once the broadcast stops being watched. `setTarget(targetBps: ...)` sends another target, `0` sends none, and `null` follows the viewers again. Ceilings or a target past 2^53 - 1 bps, the most a PROBE target carries, throw `OutOfRangeMoqException`. Client viewers survive reconnects and read `null` while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ConnectOptions(versions: ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), listen to `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index f364497668d..219ac0e1a66 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -94,8 +94,9 @@ import ( // Publish encoded frames, or raw pixels with the codec inside the binding. // opusInit, packet, pts (90 kHz ticks), and rgba come from your encoder or capture source. -publication, _ := client.CreateBroadcast("my-stream.hang") -broadcast := publication.Broadcast() +// Hidden until the catalog is filled; keep the route reachable while publishing. +route, _ := client.Route("my-stream.hang", moq.RouteOptions{Hidden: true}) +broadcast, _ := route.Broadcast() audio, _ := moqmedia.NewAudioTrackProducer(broadcast, moqmedia.Named{}, moqmedia.AudioInit{Format: moqmedia.AudioFormatOpus, Data: opusInit}) timestamp := moq.Timestamp{Value: 960, Scale: 48_000} // 20 ms on the Opus sample clock _ = audio.WriteFrame(moq.Frame{Payload: packet, Timestamp: ×tamp}) @@ -109,7 +110,7 @@ video, _ := moqvideo.NewProducer(catalogProducer, moqvideo.ProducerOptions{ Track: &track, }) _ = video.Write(moqvideo.Frame{Timestamp: moq.Timestamp{Value: pts, Scale: 90_000}, Data: rgba}) -_ = publication.Announce(moq.AnnounceRoute{}) // each broadcast mints a fresh instance +_ = route.Announce() // each route mints a fresh instance (route.Instance()) _ = audio.Finish() _ = video.Finish() broadcast.Close() // keep the producer reachable while publishing, then close explicitly @@ -124,7 +125,7 @@ one to one; the API reference has the names, and [Layers](/lib/layers) shows which module holds each. - **Context cancellation.** Every call that can block takes a `context.Context` first, and cancelling it tears down the native work, not just your wait. A one-shot call (`Request`, `FetchGroup`, `Server.Accept`) aborts alone; a stream read (`Next`, `ReadFrame`, and the iterators over them) cancels the stream it reads. -- **Keep owners reachable.** An origin from `moq.NewOriginProducer` has no `Close`. It ends when the garbage collector reaches its last owner (each producer, published broadcast, and `OriginRequests`), and its consumers then fail with `moq.ErrClosed`. +- **Keep owners reachable.** An origin from `moq.NewOriginProducer` has no `Close`. It ends when the garbage collector reaches its last owner (each producer and `Route`), and its consumers then fail with `moq.ErrClosed`. A `Route` the collector reclaims is retracted, so keep it reachable while it should stay announced, or end it with `Cancel()`. - **Bandwidth ownership.** An encoder you manage can reserve a share of the session's bandwidth. Reuse its reservation when the ceiling changes; before abandoning or replacing it, call `Update(0)` to return its share and automatic probe ceiling without waiting for garbage collection. The track can stay subscribed and the reservation can be reused. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `Cut()`: after every frame, or less often to batch frames into fewer groups. - **Timeline breaks.** On a seek or pause, call `Discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 69f64df188b..41521578862 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -29,19 +29,19 @@ const connection = await Moq.Connection.connect({ consume: origin, }); -const publication = origin.createBroadcast(Moq.Path.from("chat.room")); -const broadcast = publication.broadcast; -const track = broadcast.createTrack("messages", { timescale: Moq.Time.Timescale.MILLI }); +// Hidden until its first track exists, then announced. +const route = origin.route(Moq.Path.from("chat.room"), { hidden: true }); +const track = route.broadcast.createTrack("messages", { timescale: Moq.Time.Timescale.MILLI }); const group = track.appendGroup(); group.writeFrame({ payload: new TextEncoder().encode("hello"), timestamp: Moq.Time.Timestamp.now() }); group.finish(); -publication.announce(); +route.announce(); ``` -- **The origin holds the broadcasts, not the connection.** Closing a session unannounces them and leaves them created for the next one. A publication controls announcements; its `broadcast` fills tracks. The broadcast is invisible, locally and remotely, until the publication calls `announce()`. -- **Answer claimed paths with `using`.** `requests(prefix)` claims a prefix and yields each requested path. Use `using prepared = request.prepare()`, fill its broadcast, then `prepared.publish()` to answer with a new stream under a fresh instance and keep the `Publication` it returns. Leaving the scope without publishing, including on a throw, refuses the request as unroutable. Explicit `prepared.close()` or closing its unpublished broadcast does the same; disposal after publishing leaves the returned publication and its fill broadcast live. Reject before preparing with `request.reject(err)`. A retained, unclosed prepared answer keeps the request pending; JavaScript garbage collection provides no prompt cleanup guarantee. +- **The origin holds the routes, not the connection.** `origin.route(path)` creates a route that owns a new broadcast; fill its tracks through `route.broadcast`. Closing a session withdraws its announcements and leaves the routes for the next one. A route is visible at once unless created `{ hidden: true }`, which keeps it invisible, locally and remotely, until `announce()`. `withdraw()` hides it again and `announce()` brings the same stream back. `close()` retracts it and closes its broadcast, as closing the broadcast does. +- **Answer claimed paths with a route.** `origin.routePrefix(prefix)` claims a prefix, and `route.requested()` yields each requested path. Answer with `request.route()`, a new exact route under a fresh instance, or `request.route({ hidden: true })` to fill its broadcast before `announce()` answers the requesters; closing it or its broadcast before then refuses them as unroutable, so `using job = request.route({ hidden: true })` refuses on a throw. Serve a broadcast you already hold with `request.serve(broadcast)`, or refuse with `request.reject(err)`. - **End content by finishing tracks.** A broadcast has no finished state. When the input ends, `finish()` each track, then `close()` it; closing a track without finishing aborts it. The broadcast stays announced and keeps serving them until you `close()` it. How long to keep it up for late readers is yours to decide. -- **Requests can pin an instance.** `consumer.request(path, { instance })` resolves only through a route announcing that [publisher instance](/concept/moq-lite#publisher-instances). The resolved broadcast's `instance` names the stream it came through, pinned or not. A publication mints a random instance and keeps it across `announce()`; pass `announce({ instance, epoch })` only for a publisher that continues its group sequences across restarts and raises the epoch each time. +- **Requests can pin an instance.** `consumer.request(path, { instance })` resolves only through a route announcing that [publisher instance](/concept/moq-lite#publisher-instances). The resolved broadcast's `instance` names the stream it came through, pinned or not. A route mints a random instance when it is created and keeps it across `withdraw()` and `announce()`; pass `origin.route(path, { instance, epoch })` only for a publisher that continues its group sequences across restarts and raises the epoch each time. - **Follow restarts.** `origin.follow(path)` follows whichever publisher instance serves the path: its `active` changes to a fresh broadcast on a restart, clears on an end, and resolves again on the next start, so read it reactively and close it when done. Instances are never stitched, so subscribe again to each new broadcast. Another route of the same instance taking over (instances travel only on `moq-lite-07-wip`; older wires mint one per announcement) keeps `active` as is, and each track subscription resumes there from the first group it lacks. A refusal ends it. Pass `{ instance }` to pin one stream, which it waits for again after an end. `request(path)` instead keeps its accepted instance and ends once that instance stops serving; while pending, it fails `Unroutable` once discovery of its path has synced without a route for it. To list what is live, iterate `announced(scope)`. See [identity and recovery](/concept/identity) to choose between following and holding one instance. - **Discovery follows what you watch.** A `consume` origin asks the relay for announcements only under the prefixes its readers watch with `announced(scope)`, `request(path)`, or `follow(path)`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. Every request and follower watches its path from creation until closed, so it outlives the listing that found it. A relay that refuses an announce request downgrades that session: requests subscribe blind through it, and followers keep waiting for a session that can discover. - **Connections share by URL and versions.** `new Connection({ url })` pools and reconnects with backoff, which the elements use. An ordered `versions` list, spelled like `moq-lite-06` as in Rust, applies to both WebTransport and WebSocket; equivalent lists share, while a different order or an omitted list gets its own pool entry. Supplying your own transport options or origin selects a private loop. Receive estimates are on demand: observe `connection.probe` reactively or subscribe while you need them; `peek()` alone opens no PROBE stream. @@ -58,7 +58,7 @@ publication.announce(); - **Subscription defaults.** `Track.Subscription.default()` returns the default subscription, whose zero `delay.max` skips a superseded group at once; calling `subscribe()` with no options means the same. An omitted `delay` field means the same zero; `max: null` sets no subscriber limit. - **A subscription asks for `ranges`.** Each [range](/concept/moq-lite#subscriptions) starts and ends at an `absolute` group, one `relative` to the latest, or the group containing a `time` (a `Timestamp`), and a reader reads only its own ranges. A read whose ranges all end finishes once every group in them is handed out, dropped, or skipped, as in Rust. A time anchor needs a timed track and `moq-lite-07-wip` over a session. Passing the old `groups` key throws a `TypeError` naming `ranges`; `withRange` only narrows reads locally. - **Hidden paths** stay out of discovery unless the announce request opts in. See [hidden broadcasts](/concept/moq-lite#hidden-broadcasts). -- **Authorization is in band.** On moq-lite 07 (opt in with `versions: ["moq-lite-07-wip", "moq-lite-06"]`, listing every fallback you still want) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `auth.grant` watches what the relay lets this side publish and subscribe to, and `auth.add(token)` presents another token without reconnecting. Publishing outside the grant closes the connection with `SessionCode.Unauthorized`, naming the path. On moq-lite, a subscription or track listing the grant stops covering resets with `StreamCode.Unauthorized` and the session stays up. On moq-transport, `auth.add(token)` keeps the token even without the extension, and a broadcast announced with the `Auth.Credential` it returns (`publication.announce({ auth })`) carries it on that announcement's `PUBLISH_NAMESPACE`; announcing again with another renews the request. A `Connection`'s `auth` handle (a getter on a pooled connection, following its URL) outlives its sessions: a token added there is presented on every reconnect and keeps riding the announcements that name it, with no re-add or re-announce. A one-shot session's `auth` ends with it, unless `Connection.connect` was given a `new Auth.Handle()` as `auth`. +- **Authorization is in band.** On moq-lite 07 (opt in with `versions: ["moq-lite-07-wip", "moq-lite-06"]`, listing every fallback you still want) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `auth.grant` watches what the relay lets this side publish and subscribe to, and `auth.add(token)` presents another token without reconnecting. Publishing outside the grant closes the connection with `SessionCode.Unauthorized`, naming the path. On moq-lite, a subscription or track listing the grant stops covering resets with `StreamCode.Unauthorized` and the session stays up. On moq-transport, `auth.add(token)` keeps the token even without the extension, and a route created with the `Auth.Credential` it returns (`origin.route(path, { auth })`) carries it on that announcement's `PUBLISH_NAMESPACE`; `route.setAuth(other)` renews the request. A `Connection`'s `auth` handle (a getter on a pooled connection, following its URL) outlives its sessions: a token added there is presented on every reconnect and keeps riding the announcements that name it, with no re-add or re-announce. A one-shot session's `auth` ends with it, unless `Connection.connect` was given a `new Auth.Handle()` as `auth`. - **A graceful close waits.** `await connection.close()` withdraws announcements and drains for up to one second. `moq-lite-05` and newer wait for the subscriber to receive finished tails; older Lite versions wait only for transport ACKs. IETF media streams are not drained. `abort()` ends immediately. Examples: diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 11786fe0fef..fb5954f5116 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -72,8 +72,9 @@ Moq.connect("https://relay.example.com", ClientConfig(tls = ClientTls(roots = li // Publish encoded frames, or raw pixels with the codec inside the binding. // opusInit, packet, pts, and rgba come from your encoder or capture source. Moq.connect("https://relay.example.com").use { moq -> - val publication = moq.createBroadcast("my-stream.hang") - val broadcast = publication.broadcast() + // Hidden until the catalog is filled; hold the route while it should stay announced. + val route = moq.route("my-stream.hang", RouteOptions(hidden = true)) + val broadcast = route.broadcast() val audio = dev.moq.media.TrackProducer.audio(broadcast, Named(null), AudioInit(format = AudioFormat.OPUS, data = opusInit)) audio.writeFrame(Frame(payload = packet, timestamp = Timestamp(960u, 48_000u))) audio.cut() // audio has no keyframes, so this is what gives it groups @@ -84,7 +85,7 @@ Moq.connect("https://relay.example.com").use { moq -> output = VideoEncoderOutput(codec = VideoCodec.H264, bitrate = null, gop = null, kind = autoEncoder), track = "camera"), ) video.write(VideoFrame(timestamp = pts, data = rgba)) - publication.announce(AnnounceRoute()) // the broadcast mints its own instance + route.announce() // the route mints its own instance: route.instance() audio.finish() video.finish() broadcast.end() @@ -101,7 +102,7 @@ The rest of the [shared feature list](/lib/#what-every-binding-can-do) maps one to one; the API reference has the names, and [Layers](/lib/layers) shows which module holds each. -- **`end`, not `close`.** `broadcast.end()` ends a broadcast for good. `close()`, or leaving `use { }`, releases the handle, which ends the broadcast only once no other handle to it remains, such as its publication or a `requests()` handle. +- **`end`, not `close`.** `broadcast.end()` ends a broadcast for good, retracting its route. `close()`, or leaving `use { }`, releases the handle, which ends the broadcast only once no other handle to it remains, such as its route or a `requests()` handle. A route is the opposite: closing it retracts it at once, so hold it while the broadcast should stay announced. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or less often to batch frames into fewer groups. - **Timeline breaks.** On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. - **Media reads.** `dev.moq.media.TrackConsumer`, `dev.moq.audio.Consumer`, and `dev.moq.video.Consumer` return a `Read` in order: `ReadFrame`, a `ReadGap` where media was lost, or a `ReadEnd` where the publisher stopped its encoder. A gap breaks continuity. An encoder end is not stream EOF: following frames before its endpoint are the old encoder's drain; the first at or past it starts fresh. A decoder reads everything the track still holds unless a live player sets `start = DecodeStart.LATEST` in its decoder output, which joins at the newest group and skips the cached backlog. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index a9578d94f9b..dcb3a3cc170 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -71,8 +71,9 @@ import asyncio, moq async def main(): # opus_init_bytes, payload, pts, and rgba come from your encoder or capture source. async with moq.Client("https://cdn.moq.dev/anon") as client: - publication = client.create_broadcast("my-stream.hang") - broadcast = publication.broadcast + # Hidden until announced, so viewers find a filled catalog. Hold the route: dropping it retracts it. + route = client.route("my-stream.hang", hidden=True) + broadcast = route.broadcast # Already-encoded frames: the catalog is filled from the bitstream audio = moq.media.TrackProducer.audio(broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=opus_init_bytes)) @@ -99,7 +100,7 @@ async def main(): status = moq.json.SnapshotProducer(broadcast, status_track) status.update({"state": "live", "viewers": 42}, catalog_producer.now()) - publication.announce() # each broadcast mints a fresh instance + route.announce() # each route mints a fresh instance, route.instance audio.finish() video.finish() events.finish() diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index f373a8243cf..0e46fa6ac74 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -70,7 +70,7 @@ while let Some(event) = announced.next().await { // Skip retractions. A path stays present across publisher restarts: hold // `consumer.follow(path, None)` to be handed each new run. let moq_net::announce::Event::Present(update) = event else { continue }; - let broadcast = consumer.request(&update.prefix, update.route.instance).await?; + let broadcast = consumer.request(&update.prefix, Some(update.route.instance().clone())).await?; let catalog = broadcast .track(hang::Catalog::DEFAULT_NAME)? .subscribe(hang::Catalog::default_subscription()) @@ -80,12 +80,14 @@ while let Some(event) = announced.next().await { ``` ```rust -// Publish: create and announce a broadcast on the origin, then fill it. -let mut broadcast = origin.publish("my-stream.hang", Default::default())?; -// moq-mux (from a container) or moq-video / moq-audio (from a device) fill it. -// The route retracts on `unannounce()` or when the broadcast ends. To serve a whole -// subtree on demand instead, `origin.requests("room")?` yields each requested path: -// `prepare()`, fill its broadcast, then `publish()`, or reject it. +// Publish: create a route on the origin; it owns the broadcast to fill. +let route = origin.route("my-stream.hang", RouteOptions::default())?; +// moq-mux (from a container) or moq-video / moq-audio (from a device) fill +// `route.broadcast()`. Keep the route: dropping it, or closing its broadcast, +// retracts it, and `withdraw()`/`announce()` hide and show the same stream. To +// serve a whole subtree on demand instead, `origin.route_prefix("room", ..)?` +// yields each requested path: answer with `request.route(..)`, `serve` a held +// broadcast, or `reject`. ``` The connection and origin helpers spawn their drivers. Watch diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index 634ebe17553..90c8bc15e34 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -15,15 +15,15 @@ moq-transport at setup and presents one API either way. Media is a layer above What you use it for, beyond what the concept page already describes: -- **An origin outlives the session.** Creating a broadcast returns an origin publication that controls its announcement and exposes the broadcast to fill. Standalone and Prepared fill producers cannot announce; only publishing the Prepared answer admits its publication. A reconnect announces existing publications again, and closing the session does not delete them. -- **Requests can pin an instance.** `consumer.request(path, Some(instance))` resolves only through a route announcing that [publisher instance](/concept/moq-lite#publisher-instances); `None` takes whichever route wins. The resolved consumer names its instance in `info().instance`, pinned or not. A broadcast announced with `Route::default()` serves a random instance it keeps across re-announcing; set one with `Route::with_instance(instance, epoch)` only for a publisher that continues its group sequences across restarts and raises the epoch each time. +- **An origin outlives the session.** `origin.route(path, options)` returns a `Route` that owns the broadcast to fill (`route.broadcast()`) and controls its announcement: `announce()`, `withdraw()`, `set_cost()`, and dropping the last clone retracts it. `origin.route_prefix(prefix, options)` serves requests beneath a prefix instead, each answered with `request.serve(held)`, `request.route(options)` (the path's own exact route) or `reject`. A standalone broadcast cannot announce; publish one only through a prefix route's `serve`. A reconnect announces existing routes again, and closing the session does not delete them. +- **Requests can pin an instance.** `consumer.request(path, Some(instance))` resolves only through a route announcing that [publisher instance](/concept/moq-lite#publisher-instances); `None` takes whichever route wins. The resolved consumer names its instance in `info().instance`, pinned or not. A route serves a random instance minted when it is created and kept across `withdraw()` and `announce()`; set one with `RouteOptions::with_instance(instance, epoch)` only for a publisher that continues its group sequences across restarts and raises the epoch each time. `route.instance()` names it. - **Rank several CDNs.** Dial each with its own subscribe handle, `origin.clone().with_preference(origin::Preference::new(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. Requests use the preferred link that has a route and fail over to the next; see [multiple CDNs](/concept/moq-lite#multiple-cdns). - **Request one instance, or follow them all.** `consumer.request(path, None)` resolves the instance serving a path now, and fails `Unroutable` only once discovery has synced with no route for it. `consumer.follow(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over, `None` once the path goes offline, and whatever serves it next, like JS `follow(path)`. `consumer.announced()` lists paths only as present or absent. A broadcast already resolved stays on the old instance until dropped or its route goes. See [identity and recovery](/concept/identity) to choose between following and holding one instance. - **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `request`, or `follow`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request` owns discovery of its path, so no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-rtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything. - **Dial and accept sockets.** `socket::Endpoint::new(&origin, prefix, id)` announces a hidden endpoint at `/.socket/`, used only to route dials. A session speaks one of two protocols, each with its own dial and accept. `accept_tcp()` and `accept_track()` yield an `Incoming` dial to `accept` or `reject` (dropping it rejects). `dial_tcp(peer)` and an accepted `tcp` dial yield a `socket::TcpStream`, a `group::Producer` and `group::Consumer` pair carrying one reliable, ordered byte pipe each way (finish is FIN, abort is RST, and `ready` paces the writer to the reader); `dial_track(peer, info)` and an accepted `track` dial yield a `socket::TrackStream`, this side's `track::Producer` and a `track::Subscriber` of the peer's half, subscribed reliably and in order until the application updates it, one message per group. A dial resolves once the peer accepts, and an accept checks that the claimed dialer really dialed this endpoint, waiting for its endpoint while the dial stays open. Every hop needs moq-lite-07 or moq-transport: while the origin has an older moq-lite client session whose publish half doesn't opt into hidden broadcasts (`with_hidden(true)`), dials and accepts fail with `Unsupported`. A dial to a peer behind such a hop waits, as for a peer not online yet. Session tracks are never announced or listed. See [Sockets](/concept/socket). - **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a producer that replaces it starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups with `create_group` at an explicit sequence. Readers of an aborted track resume onto the replacement when they read through an origin request, whose route always names an instance; otherwise their subscription ends with the error. - **Authored tracks default to a zero `max_age`.** `track::Info::default()` sets `max_age` to `Some(Duration::ZERO)`, the live edge only; a publisher that wants readers to reach history sets a longer bound, or `with_max_age(None)` for no publisher limit. Media tracks from `hang::container::track_info` declare `hang::container::MAX_AGE` (30 seconds). `max_age` is how long a superseded group stays fresh, never the newest group; it frees no bytes, which the cache pool's expiry reclaims. Received metadata keeps absence as no limit, and an origin's `cache_duration` can only cap it lower. -- **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track; the broadcast stays announced and keeps serving them until you close it or drop its last producer. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window. +- **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track; the broadcast stays announced and keeps serving them until you close it or drop its route. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window. - **Demand says whether anyone is watching.** `demand()` on a track, group, or broadcast says whether a subscriber is attached. First-party capture does not wait for it: video encodes while enabled and audio keeps raw PCM to encode when someone listens, so a late subscription's `delay.max` or a FETCH finds the recent past. Demand gates bandwidth reservations, transcode rungs, and on-demand video where a publisher opts in, which saves the encode but leaves nothing from before the first subscriber. Holding a broadcast or track consumer is not demand: a track consumer requests nothing until it queries, subscribes, or fetches, and those count until dropped. A shared fetch stays up until its last reader leaves. Demand rolls up: a frame being read keeps its group wanted, a group a subscription or fetch handed out keeps its track wanted until read to its end, and any wanted track keeps its broadcast wanted. - **Use the model without a runtime.** By default `moq-net` is its `poll_*` APIs and origin driver with caller-supplied time. The `async` feature adds their async wrappers, `time::run`, and both wire sessions. - **You drive the session, or `moq-tokio` does.** `connect` and `accept` return a session plus a driver that never reads the clock itself. `moq_net::time::run` polls it on tokio. `moq-tokio` hides that. A custom transport implements `moq_net::transport::poll`, and `moq_net::transport::memory::pair` links two sessions in one process with no sockets, for tests or in-process links. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 726940de7e6..cd8fc07854c 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -70,8 +70,9 @@ for try await event in try session.consume.announced(prefix: "live/", filter: "* ```swift // Publish encoded frames, or raw pixels with the codec inside the binding (VideoToolbox). // opusInit, packet, pts, and rgba come from your encoder or capture source. -let publication = try session.publish.createBroadcast(path: "my-stream.hang") -let broadcast = publication.broadcast +// Hidden until the catalog is filled; hold the route while it should stay announced. +let route = try session.publish.route(path: "my-stream.hang", hidden: true) +let broadcast = try route.broadcast let audio = try Media.TrackProducer.audio(broadcast: broadcast, initData: Media.AudioInit(format: .opus, data: opusInit)) try audio.writeFrame(packet, timestamp: Timestamp(value: 20, scale: 1_000)) try audio.cut() // audio has no keyframes, so this is what gives it groups @@ -83,7 +84,7 @@ let video = try Video.Producer( track: "camera" ) try video.write(VideoFrame(timestamp: pts, data: rgba)) -try publication.announce(route: AnnounceRoute()) // the broadcast mints its own instance +try route.announce() // the route mints its own instance: route.instance try audio.finish() try video.finish() try broadcast.close() @@ -105,7 +106,7 @@ shows which module holds each. - **Media reads.** `Media.TrackConsumer`, `Audio.Consumer`, and `Video.Consumer` yield `Read` cases in order: `.frame`, a `.gap` where media was lost, or an `.end` where the publisher stopped its encoder. A gap breaks continuity. An encoder end is not stream EOF: following frames before its endpoint are the old encoder's drain; the first at or past it starts fresh. A decoder reads everything the track still holds unless a live player sets `start: .latest` in its decoder output, which joins at the newest group and skips the cached backlog. - **Decoded frames hold decoder buffers.** Release each frame from a `Video.Consumer` promptly, or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`. - **Closing.** `session.shutdown()` requests a drain immediately; `try await session.closed()` waits up to one second and reports its result. `session.cancel(code:)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. -- **Ending cleanly.** When the input ends, finish every track, then call `try finish()` on its `Media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). +- **Ending cleanly.** When the input ends, finish every track, then call `try finish()` on its `Media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()`, or releasing its route, takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `nil` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. - **Viewers.** `session.viewers()` divides the receive estimate among the broadcasts you watch. `watch(maxBps:)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's fair share in bits per second, `nil` while there is no estimate (keep the current rendition), and `update(maxBps:)` changes the ceiling. Holding a viewer requests the estimate like `recvBandwidth()`, and releasing it releases the claim. The session sends the summed ceilings as its PROBE target; `setTarget(targetBps:)` overrides that, `0` sends none, and `nil` follows the viewers again. `watch`, `update`, and `setTarget` throw `MoqError.OutOfRange` when the ceilings or the target would pass 2^53 - 1 bps, the most a PROBE target carries. - **Authorization.** On `moq-lite-07-wip` (opt in with `Client(versions:)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `for try await grant in session.grants()` yields the `Grant` the relay sent back and each change, `nil` until it answers and while a client session reconnects. Cancelling the iterating task cancels the native wait. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index d11bc22dc22..1c2553c6d9c 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -35,6 +35,22 @@ for { } ``` +### Publishing goes through one `Route` + +`OriginProducer.CreateBroadcast(path)`, `Client.CreateBroadcast`, and `Server.CreateBroadcast` are `Route(path, moq.RouteOptions{})`, and `OriginProducer.Requests(prefix)` is `RoutePrefix(prefix, moq.RouteOptions{})`. Both return a `*Route`, which replaces `*Publication`, `*OriginRequests`, and `*BroadcastPrepared`: + +- `Publication.Broadcast()` is `Route.Broadcast()`, which now also returns an error, on a prefix route. +- `Publication.Announce(moq.AnnounceRoute{...})` is `Announce()`, and re-pricing is `SetCost(cost)`. `Unannounce()` is `Withdraw()`. +- `OriginRequests.RequestedBroadcast(ctx)` is `Route.Requested(ctx)`, which returns `(nil, nil)` once the origin closes; `All(ctx)` and `Cancel()` keep their names. Cancelling ctx no longer retracts the route, only the wait. +- `BroadcastRequest.Prepare()` then `BroadcastPrepared.Publish()` is `BroadcastRequest.Route(options)`: create it hidden to fill it first, then `Announce()`. `BroadcastPrepared.Close()` is `Route.Cancel()`. +- `Route.Instance()` is the stream's instance, minted at creation and kept across `Withdraw` and `Announce`. + +`moq.AnnounceRoute` is `moq.RouteOptions{Hidden, Cost, Instance, Epoch}`, given once at creation. A route is visible at once unless `Hidden`; set it and call `Announce()` after filling the catalog to keep the old create-then-announce order. A stable `Instance` is fixed for the route's lifetime: announcing another one is a new route. + +Keep the `*Route` reachable for as long as the broadcast should stay announced: the collector reclaiming it, or `Cancel()`, retracts it, while `BroadcastProducer.Close()` still ends both. A `*BroadcastProducer` alone no longer keeps it announced. + +`moq.Route`, the received facts in `Announce.Route`, is renamed `moq.RouteInfo`; its fields are unchanged. + ### Catalog renditions carry their warmup ([#7864](https://github.com/moq-dev/moq/pull/7864)) `ffi.MoqVideo` and `ffi.MoqAudio` (`media.Video` and `media.Audio`) gain `Warmup`, the catalog's decoder warmup, nil when absent. `media.NewTrackConsumer` and the audio and video `Subscribe` read it from the rendition and start that much earlier; a negative one is refused with an error. Only unkeyed struct literals change. diff --git a/go/wrapper/README.md b/go/wrapper/README.md index 1550a52120f..16f98f5e61b 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -138,8 +138,8 @@ import ( moqmedia "moq.dev/moq/media" ) -publication, _ := client.CreateBroadcast("room") -broadcast := publication.Broadcast() +route, _ := client.Route("room", moq.RouteOptions{Hidden: true}) +broadcast, _ := route.Broadcast() // Every JSON write is stamped, so the track is timed. JSON is small and repetitive, so // compress it on the wire. scale := uint64(1_000) @@ -148,7 +148,7 @@ status, _ := moqjson.NewSnapshotProducer(broadcast, track, moqjson.SnapshotOptio catalog, _ := moqmedia.NewCatalogProducer(broadcast) now, _ := catalog.Now() _ = status.Update(map[string]any{"viewers": 42}, now) -_ = publication.Announce(moq.AnnounceRoute{}) +_ = route.Announce() ``` Snapshot and window producers take `SnapshotOptions` or `WindowOptions`; the stream producer and diff --git a/go/wrapper/client.go b/go/wrapper/client.go index 3982bca6ad4..b94a224904a 100644 --- a/go/wrapper/client.go +++ b/go/wrapper/client.go @@ -300,11 +300,11 @@ func Dial(ctx context.Context, url string, config ClientConfig) (*Client, error) return c, nil } -// CreateBroadcast creates an unannounced broadcast at path, invisible to everyone until announced. Announce it after populating tracks. +// Route creates a route at exactly path on the publish origin, owning a new broadcast to fill. // -// See [OriginProducer.CreateBroadcast]. -func (c *Client) CreateBroadcast(path string) (*Publication, error) { - return c.publisher.CreateBroadcast(path) +// See [OriginProducer.Route]. +func (c *Client) Route(path string, options RouteOptions) (*Route, error) { + return c.publisher.Route(path, options) } // Announced lists the paths the remote announces under a pattern scope, as each becomes present or absent. diff --git a/go/wrapper/example_test.go b/go/wrapper/example_test.go index aaba35f5a70..dbc2243939e 100644 --- a/go/wrapper/example_test.go +++ b/go/wrapper/example_test.go @@ -76,7 +76,7 @@ func ExampleClient_Follow() { } // Publish a media track to a relay. -func ExampleClient_CreateBroadcast() { +func ExampleClient_Route() { ctx := context.Background() client, err := moq.Dial(ctx, "https://relay.example.com", moq.ClientConfig{}) @@ -85,17 +85,22 @@ func ExampleClient_CreateBroadcast() { } defer client.Close() - publication, err := client.CreateBroadcast("me/mic") + // Hidden until the catalog is filled; hold the route while it should stay announced. + route, err := client.Route("me/mic", moq.RouteOptions{Hidden: true}) + if err != nil { + log.Fatal(err) + } + defer route.Cancel() + broadcast, err := route.Broadcast() if err != nil { log.Fatal(err) } - broadcast := publication.Broadcast() media, err := moqmedia.NewAudioTrackProducer(broadcast, moqmedia.Named{}, moqmedia.AudioInit{Format: moqmedia.AudioFormatOpus, Data: opusHead()}) if err != nil { log.Fatal(err) } - _ = publication.Announce(moq.AnnounceRoute{}) + _ = route.Announce() // 20 ms in, counted on the Opus 48 kHz sample clock. pts := moq.Timestamp{Value: 960, Scale: 48_000} diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 3f64bdcdc39..268a5cf20e1 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -30,6 +30,22 @@ func newOrigin(t *testing.T) *moq.OriginProducer { return origin } +// newRoute creates an exact route on origin with its broadcast, kept reachable +// until the test ends: the collector reclaiming it would retract the route. +func newRoute(t *testing.T, origin *moq.OriginProducer, path string, options moq.RouteOptions) (*moq.Route, *moq.BroadcastProducer) { + t.Helper() + route, err := origin.Route(path, options) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { runtime.KeepAlive(route) }) + broadcast, err := route.Broadcast() + if err != nil { + t.Fatal(err) + } + return route, broadcast +} + // opusHead builds a valid OpusHead init buffer (RFC 7845): 48 kHz, 2 channels. func opusHead() []byte { buf := []byte("OpusHead") @@ -46,11 +62,14 @@ func TestDynamicBroadcastRequest(t *testing.T) { defer cancel() origin := newOrigin(t) - dynamic, err := origin.Requests("") + dynamic, err := origin.RoutePrefix("", moq.RouteOptions{}) if err != nil { t.Fatal(err) } defer dynamic.Cancel() + if _, err := dynamic.Broadcast(); err == nil { + t.Fatal("a prefix route owns no broadcast") + } type result struct { broadcast *moq.BroadcastConsumer @@ -62,7 +81,7 @@ func TestDynamicBroadcastRequest(t *testing.T) { requested <- result{broadcast: broadcast, err: err} }() - request, err := dynamic.RequestedBroadcast(ctx) + request, err := dynamic.Requested(ctx) if err != nil { t.Fatal(err) } @@ -74,18 +93,26 @@ func TestDynamicBroadcastRequest(t *testing.T) { t.Fatalf("path = %q, want %q", path, "dynamic/broadcast") } - prepared, err := request.Prepare() + served, err := request.Route(moq.RouteOptions{Hidden: true}) if err != nil { t.Fatal(err) } - track, err := prepared.Broadcast().PublishTrack("status", timedInfo()) + defer runtime.KeepAlive(served) + if served.Instance() == dynamic.Instance() { + t.Fatal("a job's route serves a fresh instance") + } + broadcast, err := served.Broadcast() if err != nil { t.Fatal(err) } - served, err := prepared.Publish() + track, err := broadcast.PublishTrack("status", timedInfo()) if err != nil { t.Fatal(err) } + // Only announcing answers the requester. + if err := served.Announce(); err != nil { + t.Fatal(err) + } var res result select { @@ -118,13 +145,20 @@ func TestDynamicBroadcastRequest(t *testing.T) { if err := track.Finish(); err != nil { t.Fatal(err) } - if err := served.Broadcast().Close(); err != nil { + if err := broadcast.Close(); err != nil { t.Fatal(err) } - // The publication fills the prepared broadcast, so closing one closes the other. - if _, err := prepared.Broadcast().PublishTrack("late", nil); !errors.Is(err, moq.ErrClosed) { + // The route hands out one broadcast, so closing it ends the route too. + again, err := served.Broadcast() + if err != nil { + t.Fatal(err) + } + if _, err := again.PublishTrack("late", nil); !errors.Is(err, moq.ErrClosed) { t.Fatalf("PublishTrack after close = %v, want ErrClosed", err) } + if err := served.Announce(); !errors.Is(err, moq.ErrClosed) { + t.Fatalf("Announce after close = %v, want ErrClosed", err) + } } func TestPublishAudioLifecycle(t *testing.T) { @@ -251,11 +285,7 @@ func TestAudioConsumerDelay(t *testing.T) { defer cancel() origin := newOrigin(t) - publication, err := origin.CreateBroadcast("audio-delay") - if err != nil { - t.Fatal(err) - } - broadcast := publication.Broadcast() + route, broadcast := newRoute(t, origin, "audio-delay", moq.RouteOptions{Hidden: true}) track := "mic" catalogProducer, err := moqmedia.NewCatalogProducer(broadcast) if err != nil { @@ -270,7 +300,7 @@ func TestAudioConsumerDelay(t *testing.T) { if err != nil { t.Fatal(err) } - if err := publication.Announce(moq.AnnounceRoute{}); err != nil { + if err := route.Announce(); err != nil { t.Fatal(err) } @@ -417,11 +447,7 @@ func testDecodeVideoFrame(t *testing.T, surface bool) { defer cancel() origin := newOrigin(t) - publication, err := origin.CreateBroadcast("video-decode-frame") - if err != nil { - t.Fatal(err) - } - broadcast := publication.Broadcast() + route, broadcast := newRoute(t, origin, "video-decode-frame", moq.RouteOptions{Hidden: true}) track := "camera" catalogProducer, err := moqmedia.NewCatalogProducer(broadcast) if err != nil { @@ -436,7 +462,7 @@ func testDecodeVideoFrame(t *testing.T, surface bool) { if err != nil { t.Fatal(err) } - if err := publication.Announce(moq.AnnounceRoute{}); err != nil { + if err := route.Announce(); err != nil { t.Fatal(err) } @@ -758,16 +784,12 @@ func TestLocalPublishConsumeAudio(t *testing.T) { defer cancel() origin := newOrigin(t) - publication, err := origin.CreateBroadcast("live") - if err != nil { - t.Fatal(err) - } - broadcast := publication.Broadcast() + route, broadcast := newRoute(t, origin, "live", moq.RouteOptions{Hidden: true}) media, err := moqmedia.NewAudioTrackProducer(broadcast, moqmedia.Named{}, moqmedia.AudioInit{Format: moqmedia.AudioFormatOpus, Data: opusHead()}) if err != nil { t.Fatal(err) } - if err := publication.Announce(moq.AnnounceRoute{}); err != nil { + if err := route.Announce(); err != nil { t.Fatal(err) } @@ -1302,7 +1324,7 @@ func TestConsumerCancelConcurrent(t *testing.T) { // that one request rather than the consumer it was made on. func TestRequestCancelKeepsTheOrigin(t *testing.T) { origin := newOrigin(t) - dynamic, err := origin.Requests("") + dynamic, err := origin.RoutePrefix("", moq.RouteOptions{}) if err != nil { t.Fatal(err) } @@ -1321,7 +1343,7 @@ func TestRequestCancelKeepsTheOrigin(t *testing.T) { // Take the request but never answer it, so the cancel lands on a call that is // genuinely parked rather than one that has not started. - pending, err := dynamic.RequestedBroadcast(waitCtx) + pending, err := dynamic.Requested(waitCtx) if err != nil { t.Fatal(err) } @@ -1345,19 +1367,15 @@ func TestRequestCancelKeepsTheOrigin(t *testing.T) { resolved <- err }() - next, err := dynamic.RequestedBroadcast(waitCtx) + next, err := dynamic.Requested(waitCtx) if err != nil { t.Fatal(err) } - prepared, err := next.Prepare() + served, err := next.Route(moq.RouteOptions{}) if err != nil { t.Fatal(err) } - served, err := prepared.Publish() - if err != nil { - t.Fatal(err) - } - defer served.Broadcast().Close() + defer runtime.KeepAlive(served) select { case err := <-resolved: if err != nil { @@ -1563,11 +1581,7 @@ func TestBroadcastIsReachableOnlyWhileAnnounced(t *testing.T) { defer cancel() origin := newOrigin(t) - publication, err := origin.CreateBroadcast("live") - if err != nil { - t.Fatal(err) - } - broadcast := publication.Broadcast() + route, broadcast := newRoute(t, origin, "live", moq.RouteOptions{Hidden: true}) if _, err := broadcast.PublishTrack("events", nil); err != nil { t.Fatal(err) } @@ -1576,7 +1590,10 @@ func TestBroadcastIsReachableOnlyWhileAnnounced(t *testing.T) { t.Fatal("an unannounced broadcast must be unroutable") } - if err := publication.Announce(moq.AnnounceRoute{Cost: 3}); err != nil { + if err := route.SetCost(3); err != nil { + t.Fatal(err) + } + if err := route.Announce(); err != nil { t.Fatal(err) } announced, err := consumer.Announced(moq.AnnounceOptions{}) @@ -1589,21 +1606,23 @@ func TestBroadcastIsReachableOnlyWhileAnnounced(t *testing.T) { t.Fatalf("announce: ann=%+v", ann) } - if err := publication.Unannounce(); err != nil { + if err := route.Withdraw(); err != nil { t.Fatal(err) } event := nextRoute(t, ctx, announced) if retracted, ok := event.(moq.AnnounceEventAbsent); !ok || retracted.Announce.Prefix != "live" { - t.Fatalf("unannounce: event=%+v", event) + t.Fatalf("withdraw: event=%+v", event) } if _, err := consumer.Request(ctx, "live", nil); err == nil { t.Fatal("an unannounced broadcast must be unroutable") } - if err := publication.Announce(moq.AnnounceRoute{}); err != nil { + if err := route.Announce(); err != nil { t.Fatal(err) } - nextAnnounced(t, ctx, announced) + if ann := nextAnnounced(t, ctx, announced); ann.Route.Instance != route.Instance() { + t.Fatalf("reannounce: ann=%+v, want instance %s", ann, route.Instance()) + } if _, err := consumer.Request(ctx, "live", nil); err != nil { t.Fatal(err) } @@ -1612,37 +1631,28 @@ func TestBroadcastIsReachableOnlyWhileAnnounced(t *testing.T) { } } -// A publication outliving its closed broadcast cannot announce or withdraw the -// broadcast that replaced it at the same path. -func TestStalePublicationLeavesItsReplacementAlone(t *testing.T) { +// A route outliving its closed broadcast cannot announce, re-price, or withdraw +// the route that replaced it at the same path. +func TestStaleRouteLeavesItsReplacementAlone(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), testTimeout) defer cancel() origin := newOrigin(t) - stale, err := origin.CreateBroadcast("live") - if err != nil { - t.Fatal(err) - } - if err := stale.Announce(moq.AnnounceRoute{}); err != nil { - t.Fatal(err) - } - if err := stale.Broadcast().Close(); err != nil { + stale, broadcast := newRoute(t, origin, "live", moq.RouteOptions{}) + if err := broadcast.Close(); err != nil { t.Fatal(err) } - replacement, err := origin.CreateBroadcast("live") - if err != nil { - t.Fatal(err) - } - defer replacement.Broadcast().Close() - if err := replacement.Announce(moq.AnnounceRoute{}); err != nil { - t.Fatal(err) - } - if err := stale.Announce(moq.AnnounceRoute{}); !errors.Is(err, moq.ErrClosed) { + _, replacement := newRoute(t, origin, "live", moq.RouteOptions{}) + defer replacement.Close() + if err := stale.Announce(); !errors.Is(err, moq.ErrClosed) { t.Fatalf("stale Announce = %v, want ErrClosed", err) } - if err := stale.Unannounce(); !errors.Is(err, moq.ErrClosed) { - t.Fatalf("stale Unannounce = %v, want ErrClosed", err) + if err := stale.SetCost(1); !errors.Is(err, moq.ErrClosed) { + t.Fatalf("stale SetCost = %v, want ErrClosed", err) + } + if err := stale.Withdraw(); err != nil { + t.Fatalf("stale Withdraw = %v, want a no-op", err) } if _, err := origin.Consume().Request(ctx, "live", nil); err != nil { t.Fatalf("Request = %v, want the replacement", err) @@ -1661,20 +1671,8 @@ func TestAnnouncedPatternCaptures(t *testing.T) { } defer announced.Cancel() - audio, err := origin.CreateBroadcast("room/alice/audio") - if err != nil { - t.Fatal(err) - } - if err := audio.Announce(moq.AnnounceRoute{}); err != nil { - t.Fatal(err) - } - chat, err := origin.CreateBroadcast("room/alice/chat") - if err != nil { - t.Fatal(err) - } - if err := chat.Announce(moq.AnnounceRoute{}); err != nil { - t.Fatal(err) - } + newRoute(t, origin, "room/alice/audio", moq.RouteOptions{}) + newRoute(t, origin, "room/alice/chat", moq.RouteOptions{}) update := nextAnnounced(t, ctx, announced) if update.Prefix != "room/alice/chat" { @@ -1699,13 +1697,7 @@ func TestAnnouncedExactFilterCapturesEmpty(t *testing.T) { } defer announced.Cancel() - chat, err := origin.CreateBroadcast("room/alice/chat") - if err != nil { - t.Fatal(err) - } - if err := chat.Announce(moq.AnnounceRoute{}); err != nil { - t.Fatal(err) - } + newRoute(t, origin, "room/alice/chat", moq.RouteOptions{}) update := nextAnnounced(t, ctx, announced) if update.Prefix != "room/alice/chat" { @@ -1716,9 +1708,9 @@ func TestAnnouncedExactFilterCapturesEmpty(t *testing.T) { } } -// A broadcast mints its own instance and keeps it across re-announcing. Another -// instance keeps the path present in the listing and reaches only followers. -func TestInstanceChangeReachesFollowers(t *testing.T) { +// A route mints its own instance and keeps it across re-pricing. Another route +// keeps the path present in the listing and reaches only followers. +func TestNewRouteReachesFollowers(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), testTimeout) defer cancel() @@ -1735,34 +1727,30 @@ func TestInstanceChangeReachesFollowers(t *testing.T) { } defer following.Cancel() - publication, err := origin.CreateBroadcast("instance") - if err != nil { - t.Fatal(err) - } - if err := publication.Announce(moq.AnnounceRoute{}); err != nil { - t.Fatal(err) - } + route, _ := newRoute(t, origin, "instance", moq.RouteOptions{}) minted := nextAnnounced(t, ctx, announced).Route.Instance - if minted == "" { - t.Fatal("present instance is empty, want a minted one") + if minted == "" || minted != route.Instance() { + t.Fatalf("present instance = %q, want the minted %q", minted, route.Instance()) } if _, err := following.Available(ctx); err != nil { t.Fatal(err) } - if err := publication.Announce(moq.AnnounceRoute{Cost: 1}); err != nil { + if err := route.SetCost(1); err != nil { t.Fatal(err) } stable := "cam" - if err := publication.Announce(moq.AnnounceRoute{Instance: &stable, Epoch: 1}); err != nil { - t.Fatal(err) - } + second, _ := newRoute(t, origin, "instance", moq.RouteOptions{Instance: &stable, Epoch: 1}) if _, err := following.Available(ctx); err != nil { t.Fatalf("follow after the instance change: %v", err) } - // The listing's next event is the absence, so neither re-announce reached it. - if err := publication.Unannounce(); err != nil { + // The listing's next event is the absence, so neither the re-price nor the new + // route reached it. + if err := route.Withdraw(); err != nil { + t.Fatal(err) + } + if err := second.Withdraw(); err != nil { t.Fatal(err) } event := nextRoute(t, ctx, announced) @@ -1771,8 +1759,8 @@ func TestInstanceChangeReachesFollowers(t *testing.T) { } empty := "" - if err := publication.Announce(moq.AnnounceRoute{Instance: &empty}); !errors.Is(err, moq.ErrInvalidInstance) { - t.Fatalf("Announce(empty instance) = %v, want ErrInvalidInstance", err) + if _, err := origin.Route("refused", moq.RouteOptions{Instance: &empty}); !errors.Is(err, moq.ErrInvalidInstance) { + t.Fatalf("Route(empty instance) = %v, want ErrInvalidInstance", err) } } @@ -1788,25 +1776,19 @@ func TestFollowReportsOffline(t *testing.T) { } defer following.Cancel() - publication, err := origin.CreateBroadcast("offline") - if err != nil { - t.Fatal(err) - } - if err := publication.Announce(moq.AnnounceRoute{}); err != nil { - t.Fatal(err) - } + route, _ := newRoute(t, origin, "offline", moq.RouteOptions{}) if broadcast, err := following.Available(ctx); err != nil || broadcast == nil { t.Fatalf("first Available = %v, %v; want a broadcast", broadcast, err) } - if err := publication.Unannounce(); err != nil { + if err := route.Withdraw(); err != nil { t.Fatal(err) } if broadcast, err := following.Available(ctx); err != nil || broadcast != nil { - t.Fatalf("Available after unannounce = %v, %v; want nil", broadcast, err) + t.Fatalf("Available after withdraw = %v, %v; want nil", broadcast, err) } - if err := publication.Announce(moq.AnnounceRoute{}); err != nil { + if err := route.Announce(); err != nil { t.Fatal(err) } if broadcast, err := following.Available(ctx); err != nil || broadcast == nil { @@ -1827,21 +1809,13 @@ func TestPinnedFollowReportsTakeoverOffline(t *testing.T) { } defer following.Cancel() - publication, err := origin.CreateBroadcast("pinned") - if err != nil { - t.Fatal(err) - } - if err := publication.Announce(moq.AnnounceRoute{Instance: &pinned}); err != nil { - t.Fatal(err) - } + newRoute(t, origin, "pinned", moq.RouteOptions{Instance: &pinned}) if broadcast, err := following.Available(ctx); err != nil || broadcast == nil { t.Fatalf("first Available = %v, %v; want a broadcast", broadcast, err) } other := "other" - if err := publication.Announce(moq.AnnounceRoute{Instance: &other, Epoch: 1}); err != nil { - t.Fatal(err) - } + newRoute(t, origin, "pinned", moq.RouteOptions{Instance: &other, Epoch: 1}) if broadcast, err := following.Available(ctx); err != nil || broadcast != nil { t.Fatalf("Available after takeover = %v, %v; want nil", broadcast, err) } @@ -1878,7 +1852,7 @@ func TestDynamicServesARequestUnderAPrefix(t *testing.T) { defer cancel() origin := newOrigin(t) - dynamic, err := origin.Requests("live") + dynamic, err := origin.RoutePrefix("live", moq.RouteOptions{}) if err != nil { t.Fatal(err) } @@ -1891,7 +1865,7 @@ func TestDynamicServesARequestUnderAPrefix(t *testing.T) { done <- err }() - request, err := dynamic.RequestedBroadcast(ctx) + request, err := dynamic.Requested(ctx) if err != nil { t.Fatal(err) } @@ -1899,26 +1873,22 @@ func TestDynamicServesARequestUnderAPrefix(t *testing.T) { if err != nil || path != "live/cam" { t.Fatalf("path = %q err=%v", path, err) } - prepared, err := request.Prepare() - if err != nil { - t.Fatal(err) - } - served, err := prepared.Publish() + served, err := request.Route(moq.RouteOptions{}) if err != nil { t.Fatal(err) } - defer served.Broadcast().Close() + defer runtime.KeepAlive(served) if err := <-done; err != nil { t.Fatal(err) } } -func TestClosingAPreparedAnswerRefusesTheRequest(t *testing.T) { +func TestCancellingAHiddenAnswerRefusesTheRequest(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), testTimeout) defer cancel() origin := newOrigin(t) - dynamic, err := origin.Requests("live") + dynamic, err := origin.RoutePrefix("live", moq.RouteOptions{}) if err != nil { t.Fatal(err) } @@ -1931,15 +1901,15 @@ func TestClosingAPreparedAnswerRefusesTheRequest(t *testing.T) { done <- err }() - request, err := dynamic.RequestedBroadcast(ctx) + request, err := dynamic.Requested(ctx) if err != nil { t.Fatal(err) } - prepared, err := request.Prepare() + hidden, err := request.Route(moq.RouteOptions{Hidden: true}) if err != nil { t.Fatal(err) } - prepared.Close() + hidden.Cancel() select { case err := <-done: diff --git a/go/wrapper/origin.go b/go/wrapper/origin.go index 0abeae0c06f..c3d65e0954b 100644 --- a/go/wrapper/origin.go +++ b/go/wrapper/origin.go @@ -13,7 +13,7 @@ import ( // consume sink for a full-duplex peer. // // There is no Close: the origin ends once the collector reaches every owner -// (each producer, published broadcast, and [OriginRequests]), and its consumers +// (each producer and [Route]), and its consumers // then fail with [ErrClosed]. Keep an owner reachable for as long as the origin // should live. type OriginProducer struct { @@ -35,95 +35,122 @@ func (o *OriginProducer) Consume() *OriginConsumer { return &OriginConsumer{inner: o.inner.Consume()} } -// Requests advertises prefix and serves the requests beneath it. +// Route creates a route at exactly path, owning a new broadcast to fill. // -// A route claims prefix and every path beneath it ("" claims every path). A -// service that only serves some of them rejects the rest as they are requested. -// Create, Requests if tracks are served on demand, populate, then -// [Publication.Announce]. -func (o *OriginProducer) Requests(prefix string) (*OriginRequests, error) { - inner, err := o.inner.Requests(prefix) +// The route is visible at once unless options.Hidden: a hidden route is +// invisible and unroutable, for this origin's consumers and peers alike, until +// [Route.Announce], so create it hidden to fill the catalog first. It serves a +// fresh instance, kept across [Route.Withdraw] and [Route.Announce], unless +// options names one. Keep the route reachable: [Route.Cancel], or the collector +// reclaiming it, retracts it, and [BroadcastProducer.Close] ends both. +func (o *OriginProducer) Route(path string, options RouteOptions) (*Route, error) { + inner, err := o.inner.Route(path, options) if err != nil { return nil, err } - return &OriginRequests{inner: inner}, nil + return newRoute(inner), nil } -// CreateBroadcast creates a broadcast at the given path, returning its publication. +// RoutePrefix creates a route over prefix that serves the requests beneath it. // -// The broadcast is invisible and unroutable, for this origin's consumers and -// peers alike, until [Publication.Announce]. Announce it after populating -// tracks. [BroadcastProducer.Close] ends it for good; dropping the last handle, -// the publication included, does the same. -func (o *OriginProducer) CreateBroadcast(path string) (*Publication, error) { - inner, err := o.inner.CreateBroadcast(path) +// A route claims prefix and every path beneath it ("" claims every path). A +// service that only serves some of them rejects the rest as they are requested. +// Answer each [Route.Requested] request, and keep the route reachable while it +// should stay advertised. +func (o *OriginProducer) RoutePrefix(prefix string, options RouteOptions) (*Route, error) { + inner, err := o.inner.RoutePrefix(prefix, options) if err != nil { return nil, err } - return newPublication(inner), nil + return newRoute(inner), nil } -// Publication is a broadcast published on an origin: the broadcast to fill and -// its announcement. +// Route is a route on an origin: an exact route owning one broadcast, or a +// prefix route yielding the requests beneath it. // -// The collector reclaiming it does not retract the route; [BroadcastProducer.Close] does. -type Publication struct { - inner *ffi.MoqPublication +// [Route.Cancel], or the collector reclaiming it, retracts the route, as does +// closing an exact route's broadcast; a [BroadcastProducer] alone does not keep +// it announced. +type Route struct { + inner *ffi.MoqRoute broadcast *BroadcastProducer } -func newPublication(inner *ffi.MoqPublication) *Publication { - return &Publication{inner: inner, broadcast: &BroadcastProducer{inner: inner.Broadcast()}} +func newRoute(inner *ffi.MoqRoute) *Route { + route := &Route{inner: inner} + // A prefix route owns no broadcast. + if broadcast, err := inner.Broadcast(); err == nil { + route.broadcast = &BroadcastProducer{inner: broadcast} + } + return route +} + +// Broadcast returns the broadcast an exact route owns, the same one on every +// call, or an error on a prefix route, which owns none. +func (r *Route) Broadcast() (*BroadcastProducer, error) { + if r.broadcast == nil { + _, err := r.inner.Broadcast() + return nil, err + } + return r.broadcast, nil } -// Broadcast returns the broadcast to fill, the same one on every call. -func (p *Publication) Broadcast() *BroadcastProducer { - return p.broadcast +// Instance returns the stream this route serves, minted at creation unless +// [RouteOptions] named one. +func (r *Route) Instance() string { + return r.inner.InstanceId() } -// Announce advertises the broadcast's exact path as a route. -// -// Announcing again re-prices the route in place. Until announced, the -// broadcast is invisible and unroutable for local consumers and peers alike. -// Errors with ErrClosed once the broadcast is closed. -func (p *Publication) Announce(route AnnounceRoute) error { - return p.inner.Announce(route) +// Announce makes the route visible, or keeps it so. A route from +// [BroadcastRequest.Route] also answers the requesters waiting on its path. +// Errors with ErrClosed once its broadcast is closed. +func (r *Route) Announce() error { + return r.inner.Announce() } -// Unannounce retracts the broadcast's exact-path advertisement, if any, from -// local consumers and peers alike. Tracks already in flight carry on, and -// Announce brings it back. Errors with ErrClosed once the broadcast is closed. -func (p *Publication) Unannounce() error { - return p.inner.Unannounce() +// Withdraw hides the route from local consumers and peers alike, keeping its +// broadcast and instance. Tracks already in flight carry on, and Announce +// brings the same stream back. +func (r *Route) Withdraw() error { + return r.inner.Withdraw() } -// OriginRequests streams requests for paths with no existing exact-path broadcast. -type OriginRequests struct { - inner *ffi.MoqOriginRequests +// SetCost re-prices the route in place: lower wins among routes covering the +// same prefix. A hidden route keeps the price for when it next announces. +func (r *Route) SetCost(cost uint64) error { + return r.inner.SetCost(cost) } -// RequestedBroadcast blocks until a consumer requests a path with no existing -// exact-path broadcast. -func (d *OriginRequests) RequestedBroadcast(ctx context.Context) (*BroadcastRequest, error) { - inner, err := bridge.CallHandle(ctx, d.inner.Cancel, d.inner.RequestedBroadcast) - if err != nil { +// Requested blocks until a consumer requests a path beneath this prefix route, +// returning (nil, nil) once the origin closes, and at once on an exact route. +// +// Cancelling ctx abandons only this wait: the route stays advertised. +func (r *Route) Requested(ctx context.Context) (*BroadcastRequest, error) { + inner, err := bridge.CallRelease(ctx, nil, r.inner.Requested, func(request **ffi.MoqBroadcastRequest) { + if request != nil { + (*request).Destroy() + } + }) + if err != nil || inner == nil { return nil, err } - return &BroadcastRequest{inner: inner}, nil + return &BroadcastRequest{inner: *inner}, nil } -// All ranges over requested broadcasts until the stream errors or the loop -// breaks. -func (d *OriginRequests) All(ctx context.Context) iter.Seq2[*BroadcastRequest, error] { - return bridge.Seq(ctx, d.RequestedBroadcast) +// All ranges over requested broadcasts until the route ends, a call errors, or +// the loop breaks. +func (r *Route) All(ctx context.Context) iter.Seq2[*BroadcastRequest, error] { + return bridge.Seq(ctx, r.Requested) } -// Cancel stops serving requested broadcasts and retracts the route. -func (d *OriginRequests) Cancel() { - d.inner.Cancel() +// Cancel retracts the route now, rather than when the collector reclaims it. +// Pending requests are rejected and later calls fail with ErrCancelled. An exact +// route's broadcast lives on until [BroadcastProducer.Close]. +func (r *Route) Cancel() { + r.inner.Cancel() } -// BroadcastRequest is a requested broadcast that has not been accepted yet. +// BroadcastRequest is a requested broadcast that has not been answered yet. type BroadcastRequest struct { inner *ffi.MoqBroadcastRequest } @@ -133,13 +160,17 @@ func (r *BroadcastRequest) Path() (string, error) { return r.inner.Path() } -// Prepare starts answering as a new stream under a fresh instance, hidden until published. -func (r *BroadcastRequest) Prepare() (*BroadcastPrepared, error) { - inner, err := r.inner.Prepare() +// Route answers with the path's own exact route, owning a new broadcast. +// +// It serves a fresh instance unless options names one. Created visible, it +// announces now and answers the waiting requesters; created hidden, they wait +// until [Route.Announce], so the job can fill its catalog first. +func (r *BroadcastRequest) Route(options RouteOptions) (*Route, error) { + inner, err := r.inner.Route(options) if err != nil { return nil, err } - return &BroadcastPrepared{inner: inner}, nil + return newRoute(inner), nil } // Serve answers with held content under the prefix route's continuous sequence space, @@ -153,31 +184,6 @@ func (r *BroadcastRequest) Reject(errorCode uint16) error { return r.inner.Reject(errorCode) } -// BroadcastPrepared is a claim answer being filled before announcement. -type BroadcastPrepared struct { - inner *ffi.MoqBroadcastPrepared -} - -// Broadcast returns the unannounced broadcast to fill before publishing; only Publish announces it. -func (p *BroadcastPrepared) Broadcast() *BroadcastProducer { - return &BroadcastProducer{inner: p.inner.Broadcast()} -} - -// Publish announces the answer and resolves every waiting requester, returning -// its publication. -func (p *BroadcastPrepared) Publish() (*Publication, error) { - inner, err := p.inner.Publish() - if err != nil { - return nil, err - } - return newPublication(inner), nil -} - -// Close abandons the answer if it was not published, refusing every waiting requester. -func (p *BroadcastPrepared) Close() { - p.inner.Destroy() -} - // OriginConsumer discovers and requests broadcasts published to an origin. type OriginConsumer struct { inner *ffi.MoqOriginConsumer diff --git a/go/wrapper/origin_internal_test.go b/go/wrapper/origin_internal_test.go index d0c9fd04b4e..e3f2de5544b 100644 --- a/go/wrapper/origin_internal_test.go +++ b/go/wrapper/origin_internal_test.go @@ -35,15 +35,15 @@ func TestOriginEndsWithItsProducer(t *testing.T) { } } -// An OriginRequests owns its origin: once the collector finalizes the last +// A prefix Route owns its origin: once the collector finalizes the last // OriginProducer, the route still serves and a consumer made earlier still // resolves through it. -func TestRequestsKeepTheOrigin(t *testing.T) { +func TestRouteKeepsTheOrigin(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() origin := NewOriginProducer() - dynamic, err := origin.Requests("") + dynamic, err := origin.RoutePrefix("", RouteOptions{}) if err != nil { t.Fatal(err) } @@ -62,19 +62,15 @@ func TestRequestsKeepTheOrigin(t *testing.T) { requested <- result{broadcast: broadcast, err: err} }() - request, err := dynamic.RequestedBroadcast(ctx) - if err != nil { - t.Fatalf("RequestedBroadcast err = %v, want a request", err) - } - prepared, err := request.Prepare() - if err != nil { - t.Fatal(err) + request, err := dynamic.Requested(ctx) + if err != nil || request == nil { + t.Fatalf("Requested = (%v, %v), want a request", request, err) } - served, err := prepared.Publish() + served, err := request.Route(RouteOptions{}) if err != nil { t.Fatal(err) } - defer func() { _ = served.Broadcast().Close() }() + defer func() { _ = served.broadcast.Close() }() var res result select { @@ -87,34 +83,37 @@ func TestRequestsKeepTheOrigin(t *testing.T) { } } -// Releasing a publication, which is what its finalizer does, keeps the route: -// only closing the broadcast retracts it. -func TestReleasingAPublicationKeepsItsRoute(t *testing.T) { +// Releasing a route, which is what its finalizer does, retracts it: the +// broadcast alone keeps nothing announced, though it lives on until closed. +func TestReleasingARouteRetractsIt(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() origin := NewOriginProducer() consumer := origin.Consume() - publication, err := origin.CreateBroadcast("live") + route, err := origin.Route("live", RouteOptions{}) if err != nil { t.Fatal(err) } - if err := publication.Announce(AnnounceRoute{}); err != nil { + broadcast, err := route.Broadcast() + if err != nil { t.Fatal(err) } - broadcast := publication.Broadcast() - if broadcast != publication.Broadcast() { + if again, _ := route.Broadcast(); again != broadcast { t.Fatal("Broadcast must return the same producer on every call") } - publication.inner.Destroy() - if _, err := consumer.Request(ctx, "live", nil); err != nil { - t.Fatalf("Request = %v, want the released publication's broadcast", err) + t.Fatalf("Request = %v, want the route's broadcast", err) + } + route.inner.Destroy() + + if _, err := consumer.Request(ctx, "live", nil); err == nil { + t.Fatal("a released route must be unroutable") + } + if _, err := broadcast.PublishTrack("data", nil); err != nil { + t.Fatalf("PublishTrack = %v, want the broadcast still open", err) } if err := broadcast.Close(); err != nil { t.Fatal(err) } - if _, err := consumer.Request(ctx, "live", nil); err == nil { - t.Fatal("a closed broadcast must be unroutable") - } } diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index 7abebe48368..02c28eb680d 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -10,8 +10,8 @@ import ( ) // BroadcastProducer publishes a collection of tracks. Create one at a path with -// [OriginProducer.CreateBroadcast] (or [Client.CreateBroadcast]) and take it -// from the [Publication], then publish tracks onto it. +// [OriginProducer.Route] (or [Client.Route]) and take it from the [Route], then +// publish tracks onto it. type BroadcastProducer struct { inner *ffi.MoqBroadcastProducer } @@ -19,7 +19,7 @@ type BroadcastProducer struct { // NewBroadcastProducer creates a standalone broadcast, not attached to any // origin: pass its [BroadcastProducer.Consume] result to [BroadcastRequest.Serve] // for a dynamic request, or use it for local pub/sub. To publish at a path, use -// [OriginProducer.CreateBroadcast]. +// [OriginProducer.Route]. func NewBroadcastProducer() (*BroadcastProducer, error) { inner, err := ffi.NewMoqBroadcastProducer() if err != nil { diff --git a/go/wrapper/reconnect_test.go b/go/wrapper/reconnect_test.go index 398fe4f8a66..0926f488c1e 100644 --- a/go/wrapper/reconnect_test.go +++ b/go/wrapper/reconnect_test.go @@ -184,11 +184,15 @@ func TestReconnectAcrossRelayRestart(t *testing.T) { publisher := dialWorker(t, ctx, url) defer publisher.Close() - publication, err := publisher.CreateBroadcast("live") + route, err := publisher.Route("live", moq.RouteOptions{Hidden: true}) + if err != nil { + t.Fatal(err) + } + defer route.Cancel() + broadcast, err := route.Broadcast() if err != nil { t.Fatal(err) } - broadcast := publication.Broadcast() defer broadcast.Close() track, err := broadcast.PublishTrack("data", timedInfo()) @@ -196,7 +200,7 @@ func TestReconnectAcrossRelayRestart(t *testing.T) { t.Fatal(err) } defer track.Finish() - if err := publication.Announce(moq.AnnounceRoute{}); err != nil { + if err := route.Announce(); err != nil { t.Fatal(err) } diff --git a/go/wrapper/runtime_bench_test.go b/go/wrapper/runtime_bench_test.go index 5507f55d70c..0d01fb69477 100644 --- a/go/wrapper/runtime_bench_test.go +++ b/go/wrapper/runtime_bench_test.go @@ -150,11 +150,15 @@ func benchThroughput(b *testing.B, c benchCase) { origin := moq.NewOriginProducerWithConfig(moq.OriginConfig{CacheCapacityBytes: &cacheBytes}) // The origin owns the cache policy; keep it until the case ends. b.Cleanup(func() { runtime.KeepAlive(origin) }) - publication, err := origin.CreateBroadcast("bench") + route, err := origin.Route("bench", moq.RouteOptions{Hidden: true}) + if err != nil { + b.Fatal(err) + } + b.Cleanup(func() { runtime.KeepAlive(route) }) + broadcast, err := route.Broadcast() if err != nil { b.Fatal(err) } - broadcast := publication.Broadcast() b.Cleanup(func() { _ = broadcast.Close() }) tracks := make([]*moq.TrackProducer, c.publishers) consumers := make([]*moq.TrackConsumer, 0, c.publishers*c.subscribers) diff --git a/go/wrapper/server.go b/go/wrapper/server.go index 2247aa52cd0..c81e5e30029 100644 --- a/go/wrapper/server.go +++ b/go/wrapper/server.go @@ -215,14 +215,14 @@ func (s *Server) CertFingerprints() ([]string, error) { return s.inner.CertFingerprints() } -// CreateBroadcast creates an unannounced broadcast at path, invisible to everyone until announced. Announce it after populating tracks. +// Route creates a route at exactly path on the publish origin, owning a new broadcast to fill. // -// See [OriginProducer.CreateBroadcast]. -func (s *Server) CreateBroadcast(path string) (*Publication, error) { +// See [OriginProducer.Route]. +func (s *Server) Route(path string, options RouteOptions) (*Route, error) { if s.publishOrigin == nil { return nil, ErrNoPublishOrigin } - return s.publishOrigin.CreateBroadcast(path) + return s.publishOrigin.Route(path, options) } // Accept returns the next incoming request, or (nil, nil) when the server stops. diff --git a/go/wrapper/types.go b/go/wrapper/types.go index 5f1b7e08c5f..787a68d6edb 100644 --- a/go/wrapper/types.go +++ b/go/wrapper/types.go @@ -33,16 +33,18 @@ type ( ProtocolKind = ffi.MoqProtocolKind // OriginConfig configures a new origin, such as its maximum cache size in bytes. OriginConfig = ffi.MoqOriginConfig - // AnnounceRoute is how a broadcast advertises its exact path: its static production Cost (lower wins) and, optionally, a stable Instance. - // A nil Instance keeps the one the broadcast minted, which it keeps across re-announcing, so a restarted - // publisher is a new stream viewers restart onto. Set one only for a publisher that continues its group - // sequences across restarts and raises Epoch on each: readers stitch every route of one instance together, - // so restarting the sequences under an old instance splices unrelated groups into their tracks. - AnnounceRoute = ffi.MoqAnnounceRoute - // Route is an observed route: the Instance of the stream it serves (routes with one instance are one continuous stream), the hop chain it took to reach an origin, and its static production and link cost (lower wins). - Route = ffi.MoqRoute + // RouteOptions is how a [Route] advertises itself: Hidden until [Route.Announce], its static + // production Cost (lower wins) and, optionally, a stable Instance. The zero value is visible at + // once, at cost 0, under a fresh instance the route keeps for its lifetime, so a restarted + // publisher is a new stream viewers restart onto. Set Instance only for a publisher that + // continues its group sequences across restarts and raises Epoch on each: readers stitch every + // route of one instance together, so restarting the sequences under an old instance splices + // unrelated groups into their tracks. + RouteOptions = ffi.MoqRouteOptions + // RouteInfo is the read-only facts on a received route: the Instance of the stream it serves (routes with one instance are one continuous stream), the hop chain it took to reach an origin, and its static production and link cost (lower wins). + RouteInfo = ffi.MoqRouteInfo // Announce is a route over a prefix: the origin-relative Prefix, what each filter - // wildcard matched (Captures), and the Route serving it. It carries no broadcast; + // wildcard matched (Captures), and the RouteInfo serving it. It carries no broadcast; // resolve a path with [OriginConsumer.Request]. Captures is a required slice, // empty when the filter has no wildcards. Announce = ffi.MoqAnnounce diff --git a/js/crypto/README.md b/js/crypto/README.md index 29316633daf..09b85db380c 100644 --- a/js/crypto/README.md +++ b/js/crypto/README.md @@ -36,10 +36,11 @@ const { Broadcast, SecretKey } = Sign; const key = await SecretKey.generate(); const path = Path.from(`mesh/${key.public}/agent`); -const publication = origin.createBroadcast(path); -const signed = new Broadcast.Producer(publication.broadcast, key, path); +const route = origin.route(path, { hidden: true }); +// Signs under the route's instance, which readers verify against. +const signed = new Broadcast.Producer(route.broadcast, key, { path, instance: route.instance }); const messages = signed.createTrack("messages"); -publication.announce({ instance: signed.instance }); +route.announce(); const group = messages.appendGroup(); await group.writeFrame(undefined, payload); @@ -87,15 +88,19 @@ every write is checked against it. `close()` ends the wrapped broadcast. import { E2ee } from "@moq/crypto"; import { Time } from "@moq/net"; -const { Broadcast, Credential } = E2ee; +const { Broadcast, Credential, Epoch } = E2ee; const credential = new Credential({ context, kid, secret }); const generation = credential.produce(); -const publication = origin.createBroadcast(await credential.path("meeting.hang")); -const video = await new Broadcast.Producer(publication.broadcast, generation).createTrack("video", { +// The route's instance names the generation's epoch, so subscribers find the key. +const route = origin.route(await credential.path("meeting.hang"), { + hidden: true, + instance: Epoch.instance(generation.epoch), +}); +const video = await new Broadcast.Producer(route.broadcast, generation).createTrack("video", { timescale: Time.Timescale.MILLI, }); -publication.announce({ epoch: generation.epoch }); +route.announce(); const group = video.appendGroup(); await group.writeFrame(Time.Timestamp.now(), frame); @@ -105,8 +110,8 @@ video.close(); ``` A subscriber follows `credential.path(semantic)` with `origin.follow(path)`. It takes each -instance's epoch from the broadcast it resolved, `broadcast.epoch` (or from the application's -channel on a wire without route epochs), so the key always matches the instance it reads. It +instance's epoch from the broadcast it resolved, `Epoch.of(broadcast)` (or from the application's +channel on a wire without route instances), so the key always matches the instance it reads. It binds the epoch with `credential.consume(epoch)` and wraps the broadcast in a `Broadcast.Consumer`. Its `subscribe(semantic)` opens the track a decrypted catalog names, and `close()` releases the diff --git a/js/crypto/src/e2ee/index.ts b/js/crypto/src/e2ee/index.ts index 949c58e758e..c7db9f1270a 100644 --- a/js/crypto/src/e2ee/index.ts +++ b/js/crypto/src/e2ee/index.ts @@ -7,8 +7,8 @@ * * A {@link Credential} is what the application distributes out of band. Each publisher instance * calls {@link Credential.produce} to mint a {@link Generation.Producer} and wraps its `@moq/net` - * broadcast in a {@link Broadcast.Producer}, announcing the generation's epoch as its route's - * instance. Subscribers follow the path, read each instance's epoch with {@link Epoch.of} from + * broadcast in a {@link Broadcast.Producer}, creating its route under the generation's epoch as + * its instance. Subscribers follow the path, read each instance's epoch with {@link Epoch.of} from * the broadcast it resolved, bind a {@link Generation.Consumer} with * {@link Credential.consume}, and wrap the broadcast in a {@link Broadcast.Consumer}. Both sides name tracks by their semantic names; only the * derived physical names reach `@moq/net`. @@ -16,9 +16,12 @@ * ```ts * const credential = new Credential({ context, kid, secret }); * const generation = credential.produce(); - * const publication = origin.createBroadcast(await credential.path("meeting.hang")); - * const video = await new Broadcast.Producer(publication.broadcast, generation).createTrack("video", { timescale }); - * publication.announce({ instance: Epoch.instance(generation.epoch) }); + * const route = origin.route(await credential.path("meeting.hang"), { + * hidden: true, + * instance: Epoch.instance(generation.epoch), + * }); + * const video = await new Broadcast.Producer(route.broadcast, generation).createTrack("video", { timescale }); + * route.announce(); * * const group = video.appendGroup(); * await group.writeFrame(timestamp, frame); diff --git a/js/crypto/src/e2ee/transport.test.ts b/js/crypto/src/e2ee/transport.test.ts index 176690027de..712f105a042 100644 --- a/js/crypto/src/e2ee/transport.test.ts +++ b/js/crypto/src/e2ee/transport.test.ts @@ -62,12 +62,12 @@ for (const [name, protocol, routed, timed] of transports) { const cred = credential(); const generation = cred.produce(); const path = await cred.path("meeting.hang"); - const broadcastPublication = publisher.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; + const broadcastRoute = publisher.route(path, { hidden: true, instance: Epoch.instance(generation.epoch) }); + const broadcast = broadcastRoute.broadcast; const video = await new Protected.Producer(broadcast, generation).createTrack("video", { timescale: Time.Timescale.MILLI, }); - broadcastPublication.announce({ instance: Epoch.instance(generation.epoch) }); + broadcastRoute.announce(); const group = video.appendGroup(); await group.writeFrame(ms(1), encoder.encode("keyframe")); @@ -119,12 +119,12 @@ for (const [name, protocol] of [ const cred = credential(); const generation = cred.produce(); const path = await cred.path("meeting.hang"); - const broadcastPublication = publisher.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; + const broadcastRoute = publisher.route(path, { hidden: true, instance: Epoch.instance(generation.epoch) }); + const broadcast = broadcastRoute.broadcast; const audio = await new Protected.Producer(broadcast, generation).createDatagrams("audio", { timescale: Time.Timescale.MILLI, }); - broadcastPublication.announce({ instance: Epoch.instance(generation.epoch) }); + broadcastRoute.announce(); const remote = await active(subscriber, path); const consumer = await new Protected.Consumer( diff --git a/js/crypto/src/sign/broadcast.ts b/js/crypto/src/sign/broadcast.ts index fecfde5f21d..5d7ffebb90a 100644 --- a/js/crypto/src/sign/broadcast.ts +++ b/js/crypto/src/sign/broadcast.ts @@ -15,23 +15,32 @@ import * as Track from "./track.ts"; /** * The publishing side of a signed broadcast. * - * Mints a fresh instance, so a restart never signs a sequence an earlier instance already signed. - * Announce the wrapped broadcast with {@link instance} on its route. + * Signs under the instance of the route that serves it, which a route mints fresh, so a restart + * never signs a sequence an earlier instance already signed. */ export class Producer { - /** The instance this producer signs under, to announce on the broadcast's route. */ - readonly instance: Instance.Valid = Instance.random(); + /** The instance this producer signs under: the route's that serves the broadcast. */ + readonly instance: Instance.Valid; #inner: NetBroadcast.Producer; #key: SecretKey; #path: Path.Valid; // Each track's lowest unsigned sequence, kept across the track's replacements. #sequences = new Map(); - /** Sign `inner` with `key`, as the broadcast at application path `path`, taking ownership of it: {@link close} ends it. */ - constructor(inner: NetBroadcast.Producer, key: SecretKey, path: Path.Valid) { + /** + * Sign `inner` with `key`, as the broadcast at application path `path` served under `instance`, + * taking ownership of it: {@link close} ends it. Pass the instance of the route that serves it, + * such as `route.instance` for the route that owns `inner`. + */ + constructor( + inner: NetBroadcast.Producer, + key: SecretKey, + { path, instance }: { path: Path.Valid; instance: Instance.Valid }, + ) { this.#inner = inner; this.#key = key; this.#path = path; + this.instance = instance; } /** Settles with `null` once the wrapped broadcast closes, as `@moq/net`'s `closed` does. */ diff --git a/js/crypto/src/sign/index.ts b/js/crypto/src/sign/index.ts index b840f107158..8b9e5b4704d 100644 --- a/js/crypto/src/sign/index.ts +++ b/js/crypto/src/sign/index.ts @@ -13,10 +13,10 @@ * ```ts * const key = await SecretKey.generate(); * const path = Path.from(`mesh/${key.public}/agent`); - * const publication = origin.createBroadcast(path); - * const signed = new Broadcast.Producer(publication.broadcast, key, path); + * const route = origin.route(path, { hidden: true }); + * const signed = new Broadcast.Producer(route.broadcast, key, { path, instance: route.instance }); * const messages = signed.createTrack("messages"); - * publication.announce({ instance: signed.instance }); + * route.announce(); * * const group = messages.appendGroup(); * await group.writeFrame(undefined, payload); diff --git a/js/crypto/src/sign/sign.test.ts b/js/crypto/src/sign/sign.test.ts index d2f1d01da46..342bb759c24 100644 --- a/js/crypto/src/sign/sign.test.ts +++ b/js/crypto/src/sign/sign.test.ts @@ -46,15 +46,14 @@ async function active(origin: Origin.Producer, path: Path.Valid): Promise({ track, deltas: false }); - broadcastPublication.announce(); + broadcastRoute.announce(); const request = origin.request(Moq.Path.from("room/alice")); const active = request.active.peek(); if (!active) throw new Error("request did not resolve"); diff --git a/js/moq-boy/src/game.test.ts b/js/moq-boy/src/game.test.ts index 4070d14ef80..57f48e84873 100644 --- a/js/moq-boy/src/game.test.ts +++ b/js/moq-boy/src/game.test.ts @@ -58,8 +58,7 @@ test("status skips values that fail the schema and ends when the track errors", const connection = new Moq.Connection({ enabled: false }); const origin = new Moq.Origin.Producer(); - const publication = origin.createBroadcast(Moq.Path.from("game", "test")); - publication.announce(); + const publication = origin.route(Moq.Path.from("game", "test")); const track = publication.broadcast.createTrack("status"); // One finished group per status, so between statuses the loop waits on the next group. diff --git a/js/moq-boy/src/game.ts b/js/moq-boy/src/game.ts index bbfff3d1d06..7c8fa6a6fb3 100644 --- a/js/moq-boy/src/game.ts +++ b/js/moq-boy/src/game.ts @@ -323,13 +323,10 @@ export class Game { const viewerId = Math.random().toString(36).slice(2, 8); this.viewerId.set(viewerId); - const viewerBroadcastPublication = origin.createBroadcast( - Moq.Path.from(this.#viewerPrefix, this.sessionId, viewerId), - ); - const viewerBroadcast = viewerBroadcastPublication.broadcast; - viewerBroadcastPublication.announce(); + const viewerRoute = origin.route(Moq.Path.from(this.#viewerPrefix, this.sessionId, viewerId)); + const viewerBroadcast = viewerRoute.broadcast; effect.cleanup(() => { - viewerBroadcast.close(); + viewerRoute.close(); this.viewerId.set(undefined); }); diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 2804c5431d1..598de2f1853 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -40,6 +40,48 @@ currently refuses them while its separate datagram-track adapter is implemented. `Announce.Event` is `{ kind: "present" | "absent" } & Announce`. Another instance taking a path over keeps it present, and a route's cost or hops changing is not reported, so `start`, `update`, `restart` and `end` are gone. Map `"start"` to `"present"` and `"end"` to `"absent"`, and drop `"update"` branches. Where you requested the path again on `"restart"`, hold `origin.follow(path)`: its `active` moves to each new instance's broadcast. +### One `Origin.Route` handle replaces publications, claims, and prepared answers + +`Origin.Producer.createBroadcast`, `requests`, and `requestsRoute`, and the `Origin.Publication`, `Origin.Prepared`, and `Origin.Requests` classes are gone. +An `Origin.Route` owns what you publish: `origin.route(path, options?)` creates an exact route that owns a new broadcast, and `origin.routePrefix(prefix, options?)` creates a prefix route that yields requests. +A route is visible at once unless created with `{ hidden: true }`; `announce()` and `withdraw()` toggle it, `announced` says which, and `close()` retracts it and closes its broadcast, as closing the broadcast does. +Its `instance` is minted when the route is created and kept across `withdraw()` and `announce()`, so a reader continues rather than restarts. A new route is a new stream. +`RouteOptions` sets what `announce(route)` took: `cost`, `auth`, and a stable `instance` with its `epoch`. Re-price with `setCost(cost)` and swap the credential with `setAuth(auth)`. + +```ts +// Before +const publication = origin.createBroadcast(path); +publication.broadcast.createTrack("catalog.json"); +publication.announce({ cost: 5n }); +publication.unannounce(); + +// After +const route = origin.route(path, { hidden: true, cost: 5n }); +route.broadcast.createTrack("catalog.json"); +route.announce(); +route.withdraw(); // announce() again continues the same instance +``` + +Drop the separate `announce()` call when nothing needs filling first: `origin.route(path)` is already visible. +A prefix route replaces `requests(prefix)`: iterate `route.requested()` as before, and answer each request with `serve(broadcast)`, `reject(err)`, or `request.route(options?)`, which replaces `prepare()` and `Prepared.publish()`. +A job's route is visible at once and answers the waiting requesters unless created hidden; a hidden one answers them on `announce()`, and closing it or its broadcast before then refuses them as `Unroutable`. + +```ts +// Before +using prepared = request.prepare(); +prepared.broadcast.createTrack("video"); +const publication = prepared.publish(); + +// After +const job = request.route({ hidden: true }); +job.broadcast.createTrack("video"); +job.announce(); +``` + +`route.broadcast` throws on a prefix route, and `requested()` ends at once on an exact one. +The route metadata interface `Origin.Route` is now the read-only `Origin.RouteInfo`, carried on announce events; applications never build one. +`Origin.Table` exposes `route` and `routePrefix` in place of `createBroadcast`, `requests`, and `requestsRoute`, and `Origin.RequestSlot` and `Origin.RouteEntry` are no longer exported. + ### Opens wait their turn for stream credit ([#7894](https://github.com/moq-dev/moq/pull/7894)) `NoStreamCredit` is removed: a request no longer fails when the peer grants no more streams. Every open waits for credit, and returning credit goes to the open with the highest `sendOrder`. A request's 10s deadline runs only while none of its streams waits to open. diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 3d7994b6aa3..d121e0b669d 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -11,7 +11,7 @@ export namespace Announce { export interface Announce { captures: Path.Pattern[] | undefined; prefix: Path.Valid; - route: Origin.Route; + route: Origin.RouteInfo; } export class Consumer { [Symbol.asyncIterator](): AsyncGenerator; @@ -466,37 +466,19 @@ export namespace Origin { } export type Hop = infer; export const HopSchema: $ZodBranded, "Hop", "out">; - export class Prepared { - [Symbol.dispose](): void; - readonly broadcast: Broadcast.Producer; - close(): void; - publish(): Origin.Publication; - } export class Producer implements Origin.Table { constructor(); announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; close(abort?: Error): void; get closed(): Signals.GetPromise; consume(): Origin.Consumer; - createBroadcast(path: Path.Valid): Origin.Publication; get discovery(): Signals.Getter; follow(path: Path.Valid, options?: Origin.FollowOptions): Origin.Following; request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; - requests(prefix: Path.Valid): Origin.Requests; + route(path: Path.Valid, options?: Origin.RouteOptions): Origin.Route; + routePrefix(prefix: Path.Valid, options?: Origin.RouteOptions): Origin.Route; scope(root: Path.Valid, patterns: Path.Patterns): Origin.Producer; } - export class Publication { - announce(route?: Origin.Route | { - auth?: Origin.Route["auth"]; - cost?: Origin.Route["cost"]; - epoch?: Origin.Route["epoch"]; - hops?: Origin.Route["hops"]; - instance?: Origin.Route["instance"]; - }): void; - readonly broadcast: Broadcast.Producer; - get route(): Origin.Route | undefined; - unannounce(): void; - } export interface Reader { announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; readonly closed: Signals.GetPromise; @@ -506,8 +488,8 @@ export namespace Origin { } export class Request { readonly path: Path.Valid; - prepare(): Origin.Prepared; reject(err: Error): void; + route(options?: Origin.RouteOptions): Origin.Route; serve(source: Broadcast.Producer | Broadcast.Consumer): void; } export interface RequestOptions { @@ -519,24 +501,37 @@ export namespace Origin { readonly closed: Signals.GetPromise; readonly path: Path.Valid; } - export class Requests { + export class Route { + [Symbol.dispose](): void; + announce(): void; + get announced(): boolean; + get broadcast(): Broadcast.Producer; close(): void; - readonly prefix: Path.Valid; + get instance(): Instance.Valid; requested(): AsyncIterableIterator; - get route(): Origin.Route; - } - export interface Route { + setAuth(auth?: Auth.Credential): void; + setCost(cost: Origin.Cost): void; + withdraw(): void; + } + export interface RouteInfo { + readonly auth?: Auth.Credential; + readonly cost: Origin.Cost; + readonly epoch?: bigint; + readonly hops: readonly Origin.Hop[]; + readonly instance?: Instance.Valid; + } + export interface RouteOptions { auth?: Auth.Credential; - cost: Origin.Cost; + cost?: Origin.Cost; epoch?: bigint; - hops: Origin.Hop[]; + hidden?: boolean; instance?: Instance.Valid; } export interface Table extends Origin.Reader { - createBroadcast(path: Path.Valid): Origin.Publication; - requests(prefix: Path.Valid): Origin.Requests; + route(path: Path.Valid, options?: Origin.RouteOptions): Origin.Route; + routePrefix(prefix: Path.Valid, options?: Origin.RouteOptions): Origin.Route; } - export function isAnonymous(route: Origin.Route): boolean; + export function isAnonymous(route: Origin.RouteInfo): boolean; } export namespace Path { diff --git a/js/net/bench/broadcasts.ts b/js/net/bench/broadcasts.ts index eb38662b229..6349cdc34e5 100644 --- a/js/net/bench/broadcasts.ts +++ b/js/net/bench/broadcasts.ts @@ -4,7 +4,7 @@ import { Signal } from "@moq/signals"; import type { Grant } from "../src/auth.ts"; import { Producer as BroadcastProducer } from "../src/broadcast.ts"; import { BroadcastCache } from "../src/consume.ts"; -import { HopSchema, Route } from "../src/hop.ts"; +import { HopSchema, RouteInfo } from "../src/hop.ts"; import * as Instance from "../src/instance.ts"; import { AnnounceRequest } from "../src/lite/announce.ts"; import { Publisher } from "../src/lite/publisher.ts"; @@ -15,6 +15,7 @@ import { createMockTransportPair } from "../src/mock.ts"; import { Producer } from "../src/origin.ts"; import * as Path from "../src/path.ts"; import { Stream, Writer } from "../src/stream.ts"; +import { wireOf } from "../src/wire.ts"; // Keep protocol diagnostics out of the measured CSV on stdout. console.debug = console.error; @@ -37,7 +38,7 @@ for (const scope of [ for (const observerCount of observerCounts) { const origin = new Producer(); const handles = Array.from({ length: routeCount }, (_, index) => - origin.requests(Path.from(`room/${index}${scope === "full-name" ? ".chat" : ""}`)), + origin.routePrefix(Path.from(`room/${index}${scope === "full-name" ? ".chat" : ""}`)), ); const touched = Path.from( scope === "rooted-producers" ? "0" : scope === "full-name" ? "room/0.chat" : "room/0", @@ -75,7 +76,7 @@ for (const scope of [ const start = performance.now(); for (let index = 0; index < updates; index++) { - handles[0].updateRoute({ cost: BigInt(index + 1) }); + handles[0].setCost(BigInt(index + 1)); await new Promise((resolve) => setImmediate(resolve)); } const elapsed = performance.now() - start; @@ -132,16 +133,14 @@ for (const pinned of [false, true]) { const origin = new Producer(); const reader = origin.consume(); const options = pinned ? { instance } : {}; - const publishers = Array.from({ length: routeCount }, (_, index) => { - const sourcePublication = origin.createBroadcast(Path.from(`room/${index}`)); - sourcePublication.announce({ instance }); - return sourcePublication; - }); + const publishers = Array.from({ length: routeCount }, (_, index) => + origin.route(Path.from(`room/${index}`), { instance }), + ); const background = publishers.map((_, index) => reader.request(Path.from(`room/${index}`), options)); const requests = Array.from({ length: readerCount }, () => reader.request(Path.from("room/0"), options)); const start = performance.now(); for (let index = 0; index < updates; index++) { - publishers[0].announce({ instance, cost: BigInt(index + 1) }); + publishers[0].setCost(BigInt(index + 1)); await Promise.resolve(); for (const request of requests) { if (!request.active.peek()) throw new Error("same-instance request lost its front"); @@ -234,7 +233,7 @@ const nextInstance = Instance.parse("01900000-0000-7000-8000-000000000002"); for (const pathCount of routeCounts) { for (const readerCount of observerCounts) { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room"), { instance }); + const dynamic = origin.routePrefix(Path.from("room"), { instance }); const pending = dynamic.requested(); const requests = Array.from({ length: pathCount }, (_, index) => Array.from({ length: readerCount }, () => origin.consume().request(Path.from(`room/${index}`))), @@ -247,7 +246,7 @@ for (const pathCount of routeCounts) { await Promise.resolve(); const before = requests.map((request) => request.active.peek()); const start = performance.now(); - dynamic.updateRoute({ instance: nextInstance }); + wireOf(dynamic).update({ instance: nextInstance }); await Promise.resolve(); const elapsed = performance.now() - start; for (const [index, request] of requests.entries()) { @@ -269,7 +268,7 @@ for (const routeCount of routeCounts) { for (const consumerCount of [8, 32, 128]) { const cache = new BroadcastCache(); const owners = Array.from({ length: routeCount }, () => ({})); - for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`pool/${i}`), owners[i], Route.default); + for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`pool/${i}`), owners[i], RouteInfo.default); const sources = Array.from({ length: consumerCount }, () => new BroadcastProducer()); const held = sources.map((source, i) => { const path = Path.from(`pool/${i % routeCount}/job/${i}`); @@ -278,7 +277,7 @@ for (const routeCount of routeCounts) { const touched = Path.from("pool/0/job/0"); const start = performance.now(); for (let i = 0; i < 4096; i++) { - cache.announce(Path.from("pool/0"), owners[0], { ...Route.default, cost: BigInt(i) }); + cache.announce(Path.from("pool/0"), owners[0], { ...RouteInfo.default, cost: BigInt(i) }); const shared = cache.get(touched, cache.instance(touched)); if (!shared || shared.closed !== held[0].closed) throw new Error("update replaced the source"); shared.close(); @@ -295,7 +294,7 @@ for (const routeCount of routeCounts) { for (const consumerCount of [1, 8, 32]) { const cache = new BroadcastCache(); const owners = Array.from({ length: routeCount }, () => ({})); - for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`pool/${i}`), owners[i], Route.default); + for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`pool/${i}`), owners[i], RouteInfo.default); const sources = Array.from({ length: consumerCount }, () => new BroadcastProducer()); const paths = sources.map((_, i) => Path.from(`pool/0/job/${i}`)); const held = sources.map((source, i) => cache.insert(paths[i], cache.instance(paths[i]), source.consume())); @@ -305,7 +304,7 @@ for (const routeCount of routeCounts) { let duplicates = 0; const start = performance.now(); for (let round = 0; round < 256; round++) { - if (round % 2 === 0) cache.announce(prefix, specific, { ...Route.default, instance }); + if (round % 2 === 0) cache.announce(prefix, specific, { ...RouteInfo.default, instance }); else cache.withdraw(prefix, specific); for (let i = 0; i < consumerCount; i++) { const instance = cache.instance(paths[i]); @@ -330,7 +329,7 @@ console.log("blind,announcements,consumers,invalidate_us,stale"); for (const routeCount of routeCounts) { for (const consumerCount of [1, 8, 32]) { const cache = new BroadcastCache(); - for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`other/${i}`), {}, Route.default); + for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`other/${i}`), {}, RouteInfo.default); const source = new BroadcastProducer(); const keeper = source.consume(); const paths = Array.from({ length: consumerCount }, (_, i) => Path.from(`pool/job/${i}`)); @@ -341,7 +340,7 @@ for (const routeCount of routeCounts) { for (let round = 0; round < 256; round++) { const held = paths.map((path) => cache.insert(path, cache.instance(path), source.consume())); const start = performance.now(); - cache.announce(prefix, owner, Route.default); + cache.announce(prefix, owner, RouteInfo.default); cache.withdraw(prefix, owner); elapsed += performance.now() - start; for (const path of paths) { @@ -372,7 +371,7 @@ for (const routeCount of routeCounts) { const held = []; for (let route = 0; route < routeCount; route++) { const prefix = Path.from(`route/${route}`); - cache.announce(prefix, owners[route], Route.default); + cache.announce(prefix, owners[route], RouteInfo.default); for (let consumer = 0; consumer < (route === 0 ? consumerCount : 1); consumer++) { const path = Path.from(`${prefix}/job/${consumer}`); const instance = cache.instance(path); @@ -403,9 +402,8 @@ for (const routeCount of routeCounts) { for (const observerCount of observerCounts) { const origin = new Producer(); const routes = Array.from({ length: routeCount }, (_, index) => { - const broadcastPublication = origin.createBroadcast(Path.from(`z/${index}`)); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from(`z/${index}`)); + const broadcast = broadcastRoute.broadcast; return broadcast; }); const senders = Array.from({ length: observerCount }, () => { @@ -429,9 +427,8 @@ for (const routeCount of routeCounts) { await Promise.all(senders.map((sender) => sender.entered.promise)); const start = performance.now(); for (let index = 0; index < updates; index++) { - const broadcastPublication = origin.createBroadcast(Path.from(`a/${index}`)); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from(`a/${index}`)); + const broadcast = broadcastRoute.broadcast; await new Promise((resolve) => setImmediate(resolve)); broadcast.close(); await new Promise((resolve) => setImmediate(resolve)); diff --git a/js/net/bench/fetch.ts b/js/net/bench/fetch.ts index b16a9c50d66..0728d2c2350 100644 --- a/js/net/bench/fetch.ts +++ b/js/net/bench/fetch.ts @@ -19,9 +19,8 @@ for (const groups of [2, 128]) { for (const subscribers of [1, 8]) { for (const size of [16, 1000, SEGMENT_BYTES * 2]) { const origin = new Producer(); - const publication = origin.createBroadcast(Path.from("fetch")); - publication.announce(); - const track = publication.broadcast.createTrack("video", { maxAge: Milli(60_000) }); + const route = origin.route(Path.from("fetch")); + const track = route.broadcast.createTrack("video", { maxAge: Milli(60_000) }); for (let sequence = 0; sequence < groups; sequence++) { const group = track.appendGroup(); // Only the selected group needs payloads; the rest expose cache-table scans. diff --git a/js/net/bench/fills.ts b/js/net/bench/fills.ts index df3a607ab86..498fdcb86a7 100644 --- a/js/net/bench/fills.ts +++ b/js/net/bench/fills.ts @@ -19,8 +19,7 @@ console.log("groups,subscribers,fill_us"); for (const groups of [2, 16, 128]) { for (const subscribers of [1, 8]) { const origin = new Producer(); - const publication = origin.createBroadcast(Path.from("fills")); - publication.announce(); + const publication = origin.route(Path.from("fills")); const track = publication.broadcast.createTrack("video", { maxAge: Milli(60_000) }); for (let i = 0; i < groups; i++) { const group = track.appendGroup(); diff --git a/js/net/bench/forward.ts b/js/net/bench/forward.ts index 42edb11c682..9fb7807daf5 100644 --- a/js/net/bench/forward.ts +++ b/js/net/bench/forward.ts @@ -10,7 +10,7 @@ import { AuthSession } from "../src/auth_session.ts"; import { Producer as BroadcastProducer } from "../src/broadcast.ts"; import type { Established } from "../src/connection/established.ts"; import { forwardAnnounced } from "../src/connection/forward.ts"; -import { Route } from "../src/hop.ts"; +import { RouteInfo } from "../src/hop.ts"; import { Producer } from "../src/origin.ts"; import * as Path from "../src/path.ts"; import { registerWire } from "../src/wire.ts"; @@ -52,7 +52,7 @@ class FakeSession { } const announce = (stream: Announce.Producer, prefix: Path.Valid, cost: bigint, kind: "start" | "update") => - stream.append({ prefix, captures: undefined, kind, route: Route.normalize({ cost }) }); + stream.append({ prefix, captures: undefined, kind, route: RouteInfo.normalize({ cost }) }); console.log("touched,heads,routes,update_us"); for (const touched of ["covering", "single"] as const) { diff --git a/js/net/bench/refresh.ts b/js/net/bench/refresh.ts index a4ecbbad214..916d57df29e 100644 --- a/js/net/bench/refresh.ts +++ b/js/net/bench/refresh.ts @@ -16,9 +16,8 @@ for (const retained of [1, 64, 1024]) const installed = clock.install(); const source = new Producer(); const destination = new Producer(); - const broadcastPublication = source.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = source.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producers = Array.from({ length: tracks }, (_, i) => broadcast.createTrack(`data${i}`, { refresh: 1 }), ); diff --git a/js/net/bench/requests.ts b/js/net/bench/requests.ts index 5bd6a4fa82e..44e1da5645d 100644 --- a/js/net/bench/requests.ts +++ b/js/net/bench/requests.ts @@ -28,9 +28,8 @@ for (const touched of ["watched", "unrelated"]) const origin = new Producer(); const path = Path.from("room/0"); const broadcasts = Array.from({ length: routes }, (_, i) => { - const broadcastPublication = origin.createBroadcast(Path.from(`room/${i}`)); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from(`room/${i}`)); + const broadcast = broadcastRoute.broadcast; return broadcast; }); const requests = Array.from({ length: followers }, () => origin.follow(path)); @@ -41,9 +40,8 @@ for (const touched of ["watched", "unrelated"]) for (let round = 0; round < 6; round++) { const start = performance.now(); for (let i = 0; i < 128; i++) { - const nextPublication = origin.createBroadcast(touched === "watched" ? path : Path.from("other")); - const next = nextPublication.broadcast; - nextPublication.announce(); + const nextRoute = origin.route(touched === "watched" ? path : Path.from("other")); + const next = nextRoute.broadcast; if (touched === "watched") { current.close(); current = next; @@ -73,7 +71,7 @@ console.log("unrelated,waiters,cancel_us"); for (const unrelated of [8, 128, 2048]) for (const waiters of [1, 8, 32]) { const origin = new Producer(); - origin.requestsRoute(Path.from("pending")); + origin.routePrefix(Path.from("pending")); const held = Array.from({ length: unrelated }, (_, i) => origin.request(Path.from(`pending/${i}`))); const wire = wireOf(origin.consume()); const samples: number[] = []; @@ -141,9 +139,9 @@ for (const failovers of [0, 1, 16, 128]) const sources: Broadcast[] = []; for (let i = 0; i < failovers; i++) { const instance = Instance.random(); - const primary = origin.requestsRoute(prefix, { instance, cost: 0n }); + const primary = origin.routePrefix(prefix, { instance, cost: 0n }); const ar = primary.requested(); - const br = origin.requestsRoute(prefix, { instance, cost: 1n }).requested(); + const br = origin.routePrefix(prefix, { instance, cost: 1n }).requested(); const held = origin.request(path); const source = new Broadcast(); sources.push(source); @@ -153,8 +151,8 @@ for (const failovers of [0, 1, 16, 128]) entries.push({ primary, ar, br, held }); } const instance = Instance.random(); - origin.requestsRoute(prefix, { instance }); - for (let i = 0; i < extraRoutes; i++) origin.requestsRoute(prefix, { instance, cost: BigInt(i + 1) }); + origin.routePrefix(prefix, { instance }); + for (let i = 0; i < extraRoutes; i++) origin.routePrefix(prefix, { instance, cost: BigInt(i + 1) }); const pending = []; for (const entry of entries) { entry.primary.close(); @@ -216,7 +214,7 @@ for (const operation of ["cancel-forward", "cancel-reverse", "drain-local"]) const settled: number[] = []; for (let round = 0; round < 4; round++) { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("pending")); + const dynamic = origin.routePrefix(Path.from("pending")); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const names = Array.from({ length: paths }, (_, i) => Path.from(`pending/${i}`)); @@ -274,7 +272,7 @@ for (const survivor of [false, true]) const origin = new Producer(); const prefix = Path.from("competing"); const path = Path.from("competing/touched"); - for (let i = 0; i < routes; i++) origin.requestsRoute(prefix, { cost: BigInt(i) }); + for (let i = 0; i < routes; i++) origin.routePrefix(prefix, { cost: BigInt(i) }); const wire = wireOf(origin.consume()); const kept = survivor ? new AbortController() : undefined; const remaining = kept ? wire.demand(path, undefined, kept.signal).catch(() => {}) : undefined; @@ -314,9 +312,8 @@ for (const [version, alpn] of [ const sources = []; for (const prefix of ["a", "b"]) for (let i = 0; i < namespaces; i++) { - const sourcePublication = origin.createBroadcast(Path.from(`${prefix}/${i}`)); - const source = sourcePublication.broadcast; - sourcePublication.announce(); + const sourceRoute = origin.route(Path.from(`${prefix}/${i}`)); + const source = sourceRoute.broadcast; sources.push(source); } const peers = await Promise.all( diff --git a/js/net/bench/resume-history.ts b/js/net/bench/resume-history.ts index a5e2d63bd63..fd417fbf752 100644 --- a/js/net/bench/resume-history.ts +++ b/js/net/bench/resume-history.ts @@ -216,8 +216,7 @@ async function measureOn(clock: Manual, { fronts, names: perRoute, routes, histo const publisher = new OriginProducer(); const paths = Array.from({ length: fronts }, (_, index) => Path.from(`room/${index}`)); const broadcasts: BroadcastProducer[] = paths.map((path) => { - const publication = publisher.createBroadcast(path); - publication.announce(); + const publication = publisher.route(path); return publication.broadcast; }); const payload = new Uint8Array(PAYLOAD).fill(7); diff --git a/js/net/bench/serve-browser-entry.ts b/js/net/bench/serve-browser-entry.ts index f70d07346b9..bde56cddf01 100644 --- a/js/net/bench/serve-browser-entry.ts +++ b/js/net/bench/serve-browser-entry.ts @@ -17,9 +17,8 @@ import { Timescale, Timestamp } from "../src/time.ts"; async function measure(protocol: string, groups: number, viewers: number) { const origin = new Origin(); - const broadcastPublication = origin.createBroadcast(Path.from("bench")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("bench")); + const broadcast = broadcastRoute.broadcast; const track = broadcast.createTrack("data", { maxAge: Milli(60_000), timescale: Timescale.MICRO }); const pair = createMockTransportPair(protocol === "lite" ? ALPN_05 : ALPN.DRAFT_22); const version = protocol === "lite" ? LiteVersion.DRAFT_05 : IetfVersion.DRAFT_22; diff --git a/js/net/bench/subscribe-drop.ts b/js/net/bench/subscribe-drop.ts index 892a8d9a7c0..bf4d9af8f59 100644 --- a/js/net/bench/subscribe-drop.ts +++ b/js/net/bench/subscribe-drop.ts @@ -23,9 +23,8 @@ try { for (let rep = 0; rep < reps; rep++) { const origins = Array.from({ length: publishers }, () => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("bench")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("bench")); + const broadcast = broadcastRoute.broadcast; const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); for (let sequence = 0n; sequence < BigInt(groups); sequence++) { const group = track.createGroup(sequence); diff --git a/js/net/examples/publish.ts b/js/net/examples/publish.ts index 90d90d6be64..7b1b7b27d09 100644 --- a/js/net/examples/publish.ts +++ b/js/net/examples/publish.ts @@ -7,10 +7,9 @@ async function main() { const origin = new Moq.Origin.Producer(); const connection = await Moq.Connection.connect({ url, publish: origin.consume() }); - // Create a broadcast (a collection of tracks) at a path on the origin - const broadcastPublication = origin.createBroadcast(Moq.Path.from("my-broadcast")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + // Route a path on the origin. The route owns a broadcast (a collection of tracks) and announces it. + const route = origin.route(Moq.Path.from("my-broadcast")); + const broadcast = route.broadcast; // Create the "chat" track up front. A subscriber is served directly from this // track, no requested() round-trip needed. Mirrors Rust's create_track. diff --git a/js/net/src/announced.test-util.ts b/js/net/src/announced.test-util.ts index 6f2b2732d87..5b36855a195 100644 --- a/js/net/src/announced.test-util.ts +++ b/js/net/src/announced.test-util.ts @@ -1,6 +1,6 @@ import { Signal } from "@moq/signals"; import type { Options, Routes } from "./announced"; -import type { Route } from "./hop"; +import type { RouteInfo } from "./hop"; import type * as Path from "./path"; /** A closeable announcement snapshot for tests and benchmarks. @internal */ @@ -10,7 +10,7 @@ export async function announcedView( options?: Options, ) { const stream = origin.routes(scope, options); - const value = new Signal>(new Map()); + const value = new Signal>(new Map()); const done = (async () => { for await (const event of stream) value.update((previous) => { diff --git a/js/net/src/announced.test.ts b/js/net/src/announced.test.ts index eb2ce44fe0e..87cd1fc24e2 100644 --- a/js/net/src/announced.test.ts +++ b/js/net/src/announced.test.ts @@ -2,15 +2,14 @@ import { expect, test } from "bun:test"; import { yieldNow } from "@moq/clock"; import * as Announce from "./announced.ts"; import type { Producer as BroadcastProducer } from "./broadcast.ts"; -import { Route } from "./hop.ts"; +import { RouteInfo } from "./hop.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { wireOf } from "./wire.ts"; function publish(origin: OriginProducer, path: Path.Valid): BroadcastProducer { - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; return broadcast; } @@ -20,7 +19,7 @@ test("next streams every appended event in order", async () => { const producer = new Announce.Producer(); const consumer = producer.consume(); - const route = Route.default; + const route = RouteInfo.default; producer.append({ prefix: p("a"), captures: undefined, kind: "start", route }); producer.append({ prefix: p("a"), captures: undefined, kind: "end", route }); @@ -32,7 +31,7 @@ test("a listing reports only a path becoming present or absent", async () => { const producer = new Announce.Producer(); const listing = Announce.list(producer.consume()); - const route = Route.default; + const route = RouteInfo.default; producer.append({ prefix: p("a"), captures: undefined, kind: "start", route }); producer.append({ prefix: p("a"), captures: undefined, kind: "update", route }); producer.append({ prefix: p("a"), captures: undefined, kind: "restart", route }); @@ -46,7 +45,7 @@ test("the consumer is an async iterable of the same events", async () => { const producer = new Announce.Producer(); const consumer = producer.consume(); - const route = Route.default; + const route = RouteInfo.default; producer.append({ prefix: p("a"), captures: undefined, kind: "start", route }); producer.append({ prefix: p("a"), captures: undefined, kind: "end", route }); @@ -65,7 +64,7 @@ test("a same-name re-announce is a distinct update", async () => { // The stream is a log, not a set: it carries a redundant announce as its own update rather // than collapsing it. Deciding what a repeat means belongs to the session layer, which resolves // a restart into either nothing (an identical route) or an in-place update. - const route = Route.default; + const route = RouteInfo.default; producer.append({ prefix: p("a"), captures: undefined, kind: "start", route }); producer.append({ prefix: p("a"), captures: undefined, kind: "start", route }); @@ -98,7 +97,7 @@ test("closing a consumer releases only that handle", async () => { expect(producer.closed.peek()).toBeUndefined(); // The other reader keeps the stream: an event still reaches it. - const route = Route.default; + const route = RouteInfo.default; producer.append({ prefix: p("a"), captures: undefined, kind: "start", route }); expect((await second.next())?.prefix).toBe(p("a")); @@ -179,7 +178,7 @@ const start = (prefix: string): Announce.RouteEvent => ({ prefix: p(prefix), captures: undefined, kind: "start", - route: Route.default, + route: RouteInfo.default, }); test("a stream syncs once the reader is past what was queued at the boundary", async () => { diff --git a/js/net/src/announced.ts b/js/net/src/announced.ts index 20db6927bfc..f779130dd94 100644 --- a/js/net/src/announced.ts +++ b/js/net/src/announced.ts @@ -4,7 +4,7 @@ * @module */ import { type GetPromise, type Getter, Once, Signal } from "@moq/signals"; -import type { Route } from "./hop.js"; +import type { RouteInfo } from "./hop.js"; import type * as Path from "./path.js"; /** @@ -26,7 +26,7 @@ export interface Announce { /** What the filter's wildcards stood for, when this prefix pins all of them. */ captures: Path.Pattern[] | undefined; /** Hops and cost of the route; on a retraction, its last advertised values. */ - route: Route; + route: RouteInfo; } /** diff --git a/js/net/src/auth.test.ts b/js/net/src/auth.test.ts index 0ca98b10dc6..5e1708feca9 100644 --- a/js/net/src/auth.test.ts +++ b/js/net/src/auth.test.ts @@ -311,8 +311,8 @@ describe.each([Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_22])("%s", (protocol) => { })(); await waitFor(client.auth.grant, (g) => g !== undefined); - origin.createBroadcast(Path.from("baz/ok")).announce(); - origin.createBroadcast(Path.from("foo/bar")).announce(); + origin.route(Path.from("baz/ok"), { hidden: true }).announce(); + origin.route(Path.from("foo/bar"), { hidden: true }).announce(); const info = await transport.closed; expect(info.closeCode).toBe(SessionCode.Unauthorized); @@ -332,15 +332,14 @@ describe.each([Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_22])("%s", (protocol) => { try { const unanswered = await requests.next(); if (!unanswered) throw new Error("missing token"); - const withdrawn = origin.createBroadcast(Path.from("foo/bar")); - withdrawn.announce(); + const withdrawn = origin.route(Path.from("foo/bar")); await yieldNow(); - withdrawn.unannounce(); + withdrawn.withdraw(); await yieldNow(); const issued = unanswered.accept(grant(["other"], [])); await adding; // Still enforcing: the next uncovered broadcast is the one named. - origin.createBroadcast(Path.from("still-bad")).announce(); + origin.route(Path.from("still-bad"), { hidden: true }).announce(); const info = await transport.closed; expect(info.closeCode).toBe(SessionCode.Unauthorized); expect(info.reason).toBe("unauthorized: still-bad"); @@ -367,7 +366,7 @@ describe.each([Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_22])("%s", (protocol) => { })(); await waitFor(client.auth.grant, (g) => g !== undefined); - origin.createBroadcast(Path.from("a/x")).announce(); + origin.route(Path.from("a/x"), { hidden: true }).announce(); const announced = server.routes(); const first = await nextRoute(announced); @@ -459,9 +458,8 @@ describe.each([Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_22])("%s", (protocol) => { const installed = clock.install(); const logged = spyOn(console, "debug"); const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room/x")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room/x")); + const broadcast = broadcastRoute.broadcast; const published = broadcast.createTrack("video"); published.appendGroup().writeFrame({ payload: new Uint8Array([1]) }); const { client, server } = await connect({ serverPublish: origin, protocol }); @@ -527,7 +525,9 @@ describe.each([Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_22])("%s", (protocol) => { try { const unanswered = await requests.next(); if (!unanswered) throw new Error("missing token"); - const track = new OriginProducer().createBroadcast(Path.from("room/x")).broadcast.createTrack("video"); + const track = new OriginProducer() + .route(Path.from("room/x"), { hidden: true }) + .broadcast.createTrack("video"); const reader = track.subscribe(); const ready = wireOf(client).auth.ready(Path.from("room/x"), "subscribe", { until: () => abandoned(track.demand()), @@ -552,9 +552,8 @@ describe.each([Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_22])("%s", (protocol) => { test("a subscribe abandoned while its token waits never reaches the wire", async () => { const logged = spyOn(console, "debug"); const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room/x")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room/x")); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("video"); const { client, server, transport } = await connect({ serverPublish: origin, protocol }); const requests = server.auth.requests(); @@ -591,9 +590,8 @@ describe.each([Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_22])("%s", (protocol) => { "a subscribe that regains a reader while its token waits keeps waiting (%d)", async (gap) => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room/x")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room/x")); + const broadcast = broadcastRoute.broadcast; const published = broadcast.createTrack("video"); published.appendGroup().writeFrame({ payload: new Uint8Array([7]) }); const { client, server } = await connect({ serverPublish: origin, protocol }); @@ -628,9 +626,8 @@ describe.each([Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_22])("%s", (protocol) => { test("a session's close is not a revocation of its subscriptions", async () => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room/x")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room/x")); + const broadcast = broadcastRoute.broadcast; broadcast .createTrack("video") .appendGroup() @@ -1020,9 +1017,8 @@ test("lite-07 ignores a draining session's late refusal while its successor retr test("a fetch abandoned while its token waits never reaches the wire", async () => { const logged = spyOn(console, "debug"); const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room/x")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room/x")); + const broadcast = broadcastRoute.broadcast; broadcast .createTrack("video") .appendGroup() @@ -1064,9 +1060,8 @@ test("a fetch abandoned while its token waits never reaches the wire", async () // The peer refuses a listing its token has not yet authorized, so the request waits for it. test("a listing waits for its token before reaching the wire", async () => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room/x")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room/x")); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("video"); const { client, server, transport } = await connect({ serverPublish: origin, protocol: Lite.ALPN_07_WIP }); const requests = server.auth.requests(); @@ -1102,9 +1097,8 @@ test.each(Array.from({ length: 17 }, (_, gap) => gap))( "a fetch that regains a caller while its token waits keeps waiting (%d)", async (gap) => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room/x")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room/x")); + const broadcast = broadcastRoute.broadcast; broadcast .createTrack("video") .appendGroup() @@ -1274,15 +1268,13 @@ test.each([ // moq-transport has no stream code for it, so only moq-lite resets with UNAUTHORIZED. test("a revoked grant resets its subscriptions with UNAUTHORIZED", async () => { const clientOrigin = new OriginProducer(); - const upPublication = clientOrigin.createBroadcast(Path.from("up/y")); - const up = upPublication.broadcast; - upPublication.announce(); + const upRoute = clientOrigin.route(Path.from("up/y")); + const up = upRoute.broadcast; const upTrack = up.createTrack("video"); const serverOrigin = new OriginProducer(); - const downPublication = serverOrigin.createBroadcast(Path.from("room/x")); - const down = downPublication.broadcast; - downPublication.announce(); + const downRoute = serverOrigin.route(Path.from("room/x")); + const down = downRoute.broadcast; const downTrack = down.createTrack("video"); const { client, server } = await connect({ diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index e07d002d8ca..bb2eb8337d9 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -7,7 +7,6 @@ import { type GetPromise, Once, Signal } from "@moq/signals"; import * as datagram from "./datagram.ts"; import { NotFound, StreamCode, StreamError, toStreamCode } from "./error.ts"; import type { Consumer as GroupConsumer } from "./group.ts"; -import type { Route } from "./hop.ts"; import type * as Instance from "./instance.ts"; import { hooks } from "./internal.ts"; import { Listing, listTracks, makeLister, type Tracks } from "./listing.ts"; @@ -18,17 +17,6 @@ import { registerWire, trackOf, wireOf } from "./wire.ts"; export { Tracks, type TracksEvent } from "./listing.ts"; -/** The origin callback a created broadcast uses to advertise its exact path. @internal */ -export interface Announcer { - /** Advertise or re-price this broadcast's path. */ - announce(route: Route): void; - /** Retract the advertisement from local consumers and peers alike. */ - unannounce(): void; - /** The route this broadcast's path is advertised with, if it is. */ - route(): Route | undefined; -} - -let attachAnnouncer: (producer: Producer, announcer: Announcer) => void; let stampProducer: (producer: Producer, path: Path.Valid) => void; // Info lookups pending or held on a track. @@ -386,7 +374,6 @@ function adopt(state: BroadcastState, producer: track.Producer, info: track.Info */ export class Producer { #state = new BroadcastState(); - #announcer?: Announcer; #path = Path.empty(); constructor() { @@ -406,11 +393,6 @@ export class Producer { } static { - attachAnnouncer = (producer, announcer) => { - producer.#announcer = announcer; - }; - hooks.attachAnnouncer = attachAnnouncer; - hooks.onClosed = (producer, fn) => { const closers = producer.#state.closers; closers.add(fn); @@ -493,10 +475,8 @@ export class Producer { return trackOf(name, this); } - /** End the broadcast for good: retract its route and serve no new tracks. Idempotent. */ + /** End the broadcast for good: serve no new tracks. Idempotent. */ close(): void { - this.#announcer?.unannounce(); - this.#announcer = undefined; closeState(this.#state); } } diff --git a/js/net/src/connection/close.test.ts b/js/net/src/connection/close.test.ts index 2111a17e097..d15c7c770bf 100644 --- a/js/net/src/connection/close.test.ts +++ b/js/net/src/connection/close.test.ts @@ -57,9 +57,8 @@ for (const protocol of [Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_18]) { const fin = holdFin(pair.server); const source = new Producer(); const destination = new Producer(); - const broadcastPublication = source.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = source.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const url = new URL("https://localhost/test"); const [client, server] = await Promise.all([ connect({ url, transport: pair.client, consume: destination }), diff --git a/js/net/src/connection/forward.test.ts b/js/net/src/connection/forward.test.ts index 79a9df2030a..396e9c3b40a 100644 --- a/js/net/src/connection/forward.test.ts +++ b/js/net/src/connection/forward.test.ts @@ -3,7 +3,7 @@ import { type Installed, Manual, Milli, Nano } from "@moq/clock"; import * as Announce from "../announced.ts"; import { AuthSession } from "../auth_session.ts"; import { type Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "../broadcast.ts"; -import { Route } from "../hop.ts"; +import { RouteInfo } from "../hop.ts"; import * as Instance from "../instance.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; @@ -132,7 +132,7 @@ class FakeSession { } } -function start(stream: Announce.Producer, prefix: string, route: Route = Route.default) { +function start(stream: Announce.Producer, prefix: string, route: RouteInfo = RouteInfo.default) { stream.append({ prefix: Path.from(prefix), captures: undefined, kind: "start", route }); } @@ -411,12 +411,12 @@ for (const [name, instances] of [ const narrow = origin.routes(Path.Pattern.subtree(Path.from("a/b"))); await settle(); - start(session.stream("a/b/**"), "a/b/x", { ...Route.default, instance: instances[0] }); + start(session.stream("a/b/**"), "a/b/x", { ...RouteInfo.default, instance: instances[0] }); await settle(); const broad = origin.routes(Path.Pattern.subtree(Path.from("a"))); const events = record(broad); await settle(); - start(session.stream("a/**"), "a/b/x", { ...Route.default, instance: instances[1] }); + start(session.stream("a/**"), "a/b/x", { ...RouteInfo.default, instance: instances[1] }); await settle(); expect(events).toEqual(["start a/b/x"]); diff --git a/js/net/src/connection/forward.ts b/js/net/src/connection/forward.ts index 99ea9c338f7..bb2cfb6ba6d 100644 --- a/js/net/src/connection/forward.ts +++ b/js/net/src/connection/forward.ts @@ -7,12 +7,12 @@ import { Milli, Nano } from "@moq/clock"; import { type Dispose, race } from "@moq/signals"; import type * as Announce from "../announced.ts"; -import { type Route, routesEqual } from "../hop.ts"; +import { type RouteInfo, routesEqual } from "../hop.ts"; import { coveringPrefixes } from "../internal.ts"; -import type { Producer as OriginProducer, RequestSlot, Requests } from "../origin.ts"; +import type { Producer as OriginProducer, Route } from "../origin.ts"; import * as Path from "../path.ts"; import { after } from "../util/timer.ts"; -import { wireOf } from "../wire.ts"; +import { type RequestSlot, wireOf } from "../wire.ts"; import type { Established } from "./established.ts"; /** Why a connection refuses the removed `discovery` option rather than ignoring it. */ @@ -39,9 +39,9 @@ interface Interest { * request handing over to another never retracts it. The first reporter drives it. */ interface Reported { - handle: Requests; + handle: Route; /** Each request's latest route for the prefix. */ - readonly reporters: Map; + readonly reporters: Map; } /** @@ -118,16 +118,17 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi * instance, so nothing resolved through the old one is joined again, and an in-place * update otherwise. */ - const updateReported = (existing: Reported, prefix: Path.Valid, route: Route, restart: boolean) => { - if (restart || route.epoch !== existing.handle.route.epoch) { + const updateReported = (existing: Reported, prefix: Path.Valid, route: RouteInfo, restart: boolean) => { + const current = wireOf(existing.handle).info; + if (restart || route.epoch !== current?.epoch) { // Inserted before the old one leaves, so local readers see one restart rather than // an end and a start. const handle = originWire.receive(prefix, route); existing.handle.close(); existing.handle = handle; void drive(handle, conn); - } else if (!routesEqual(existing.handle.route, route)) { - existing.handle.updateRoute(route); + } else if (!routesEqual(current, route)) { + wireOf(existing.handle).update(route); } }; @@ -289,7 +290,7 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi } /** Answer the requests under a received route by consuming them from the session. */ -async function drive(handle: Requests, conn: Established): Promise { +async function drive(handle: Route, conn: Established): Promise { const session = wireOf(conn); try { for await (const request of handle.requested()) { diff --git a/js/net/src/connection/migrate.test.ts b/js/net/src/connection/migrate.test.ts index 0eaef291ca2..eede71cf3e2 100644 --- a/js/net/src/connection/migrate.test.ts +++ b/js/net/src/connection/migrate.test.ts @@ -79,9 +79,8 @@ test("an empty GOAWAY migrates the follower to the replacement session", async ( const clock = new Manual(); const installed = clock.install(); const { dials, origin } = fleet(); - const broadcastPublication = origin.createBroadcast(Path.from("cam")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("cam")); + const broadcast = broadcastRoute.broadcast; const consume = new OriginProducer(); const reload = new Reload({ diff --git a/js/net/src/connection/pool.test.ts b/js/net/src/connection/pool.test.ts index d62e72772e2..e9dc3a9d313 100644 --- a/js/net/src/connection/pool.test.ts +++ b/js/net/src/connection/pool.test.ts @@ -13,11 +13,8 @@ import { type AcceptProps, accept as acceptSession } from "./index.ts"; import { Connection, resetShared } from "./pool.ts"; import { Reload } from "./reload.ts"; -function publish(origin: Pick, path: Path.Valid) { - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); - return broadcast; +function publish(origin: Pick, path: Path.Valid) { + return origin.route(path).broadcast; } const url = new URL("https://example.com/pool"); @@ -262,7 +259,7 @@ test("a borrowed connection origin exposes live routes and dynamic serving", asy announcement = event; }); const prefix = Path.from("on-demand"); - const route = table.requestsRoute(prefix); + const route = table.routePrefix(prefix); await advance(); expect(announcement).toMatchObject({ kind: "present", prefix }); let withdrawal: unknown; diff --git a/js/net/src/connection/reload.test.ts b/js/net/src/connection/reload.test.ts index 80e37e1e321..066835bc2f6 100644 --- a/js/net/src/connection/reload.test.ts +++ b/js/net/src/connection/reload.test.ts @@ -5,7 +5,7 @@ import * as Announce from "../announced.ts"; import { Viewers } from "../bandwidth.ts"; import type { Producer as BroadcastProducer } from "../broadcast.ts"; import { ConnectTimeout, SessionCode, SessionError, StreamCode, toTransport } from "../error.ts"; -import { Route } from "../hop.ts"; +import { RouteInfo } from "../hop.ts"; import { ALPN as IetfALPN } from "../ietf/version.ts"; import * as Lite from "../lite/index.ts"; import { createMockTransportPair, type MockTransport, textFrame } from "../mock.ts"; @@ -25,9 +25,8 @@ function accept(transport: WebTransport, url: URL, props: Omit handle.origin.peek() !== undefined); const origin = handle.origin.peek(); if (!origin) throw new Error("no origin"); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); await waitUntil(() => dials.length > 0); const first = dials[0]; @@ -835,9 +833,8 @@ for (const [name, drainEnd] of Object.entries(drainEnds)) { globalThis.WebTransport = stub as unknown as typeof WebTransport; const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const reload = new Reload({ url: new URL("https://example.com/a"), @@ -896,9 +893,8 @@ test("a retired GOAWAY predecessor still closes by its handover cap", async () = globalThis.WebTransport = stub as unknown as typeof WebTransport; const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const reload = new Reload({ url: new URL("https://example.com/"), @@ -980,9 +976,8 @@ test("closing the loop keeps the tokens until the session drains", async () => { const origin = new OriginProducer(); const reload = new Reload({ url, websocket: { enabled: false }, publish: origin.consume() }); await reload.auth.add("token"); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const first = dials[0]; if (!first) throw new Error("no first dial"); @@ -1034,7 +1029,7 @@ test("closing an announce consumer during upstream teardown does not append retr prefix: Path.from("alice/camera.hang"), captures: undefined, kind: "start", - route: Route.default, + route: RouteInfo.default, }); await consumer.next(); upstream.close(); @@ -1140,7 +1135,7 @@ test("a pump owes the retractions of the upstream it replaces", async () => { const consumer = producer.consume(); const first = new Announce.Producer(); - first.append({ prefix: Path.from("a"), captures: undefined, kind: "start", route: Route.default }); + first.append({ prefix: Path.from("a"), captures: undefined, kind: "start", route: RouteInfo.default }); first.synced(); const upstream = new Signal(first); const pump = new Effect((effect) => pumpAnnounced(effect, effect.get(upstream).consume(), producer)); diff --git a/js/net/src/connection/scope.test.ts b/js/net/src/connection/scope.test.ts index c59a729acf1..8c6e0b204c3 100644 --- a/js/net/src/connection/scope.test.ts +++ b/js/net/src/connection/scope.test.ts @@ -22,9 +22,8 @@ for (const protocol of [Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_18]) { new Path.Patterns(["room/**", "other/**"].map(Path.Pattern.parse)), ); const broadcasts = ["room/live", "room/.hidden", "other/live", "outside"].map((path) => { - const broadcastPublication = publish.createBroadcast(Path.from(path)); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = publish.route(Path.from(path)); + const broadcast = broadcastRoute.broadcast; return broadcast; }); const [client, server] = await Promise.all([ diff --git a/js/net/src/consume.test.ts b/js/net/src/consume.test.ts index 562ff925d99..04a42fa4f34 100644 --- a/js/net/src/consume.test.ts +++ b/js/net/src/consume.test.ts @@ -2,7 +2,7 @@ import { expect, test } from "bun:test"; import { Producer } from "./broadcast.ts"; import { BroadcastCache } from "./consume.ts"; import { StreamCode, StreamError } from "./error.ts"; -import { Route } from "./hop.ts"; +import { RouteInfo } from "./hop.ts"; import * as Instance from "./instance.ts"; import * as Path from "./path.ts"; @@ -13,16 +13,16 @@ test("cache identity follows the serving announcement, preserving held tracks", const broad = {}; const specific = {}; const instance = Instance.random(); - cache.announce(pool, broad, { ...Route.default, instance }); + cache.announce(pool, broad, { ...RouteInfo.default, instance }); const source = new Producer(); const track = source.createTrack("video"); const held = cache.insert(job, cache.instance(job), source.consume()); const ordered = held.track("video").subscribe().ordered(); - cache.announce(job, specific, { ...Route.default, instance }); + cache.announce(job, specific, { ...RouteInfo.default, instance }); const same = cache.get(job, cache.instance(job)); expect(same?.closed).toBe(held.closed); - cache.announce(job, specific, Route.default, true); + cache.announce(job, specific, RouteInfo.default, true); expect(cache.instance(job).route.instance).toBeUndefined(); expect(cache.get(job, cache.instance(job))).toBeUndefined(); const replacement = new Producer(); @@ -46,7 +46,7 @@ test("withdrawing one interest keeps another interest's explicit identity", () = const path = Path.from("room"); const first = {}; const second = {}; - const route = { ...Route.default, instance: Instance.random() }; + const route = { ...RouteInfo.default, instance: Instance.random() }; cache.announce(path, first, route); cache.announce(path, second, route); const source = new Producer(); @@ -70,7 +70,7 @@ test("an announcement lifecycle retires a blind cache without disturbing unrelat const held = cache.insert(path, cache.instance(path), source.consume()); const otherHeld = cache.insert(other, cache.instance(other), unrelated.consume()); const owner = {}; - cache.announce(Path.from("pool"), owner, Route.default); + cache.announce(Path.from("pool"), owner, RouteInfo.default); cache.withdraw(Path.from("pool"), owner); expect(cache.get(path, cache.instance(path))).toBeUndefined(); const same = cache.get(other, cache.instance(other)); @@ -87,10 +87,10 @@ test.each([false, true])("route alternation reuses every held instance (instance const broad = Path.from("pool"); const ownerA = {}; const ownerB = {}; - cache.announce(broad, ownerA, { ...Route.default, instance: explicit ? Instance.random() : undefined }); + cache.announce(broad, ownerA, { ...RouteInfo.default, instance: explicit ? Instance.random() : undefined }); const a = new Producer(); const heldA = cache.insert(path, cache.instance(path), a.consume()); - cache.announce(path, ownerB, { ...Route.default, instance: explicit ? Instance.random() : undefined }); + cache.announce(path, ownerB, { ...RouteInfo.default, instance: explicit ? Instance.random() : undefined }); const b = new Producer(); const heldB = cache.insert(path, cache.instance(path), b.consume()); cache.withdraw(path, ownerB); @@ -107,13 +107,13 @@ test("request validity cancels one selection period and permits the held fallbac const broad = Path.from("pool"); const a = {}; const b = {}; - cache.announce(broad, a, Route.default); + cache.announce(broad, a, RouteInfo.default); const sourceA = new Producer(); const instanceA = cache.instance(path); const heldA = cache.insert(path, instanceA, sourceA.consume()); const first = instanceA.validity?.signal; expect(first?.aborted).toBe(false); - cache.announce(path, b, Route.default); + cache.announce(path, b, RouteInfo.default); expect(first?.aborted).toBe(true); // A more specific route taking over ends the old instance's requests the way Rust does, so // players treat it as the instance going offline rather than an unexpected failure. @@ -142,16 +142,16 @@ test("request validity follows the selected interest and ignores unrelated withd const broad = {}; const first = {}; const second = {}; - cache.announce(Path.from("pool"), broad, Route.default); - cache.announce(path, first, Route.default); - cache.announce(path, second, Route.default); + cache.announce(Path.from("pool"), broad, RouteInfo.default); + cache.announce(path, first, RouteInfo.default); + cache.announce(path, second, RouteInfo.default); const source = new Producer(); const instance = cache.instance(path); const held = cache.insert(path, instance, source.consume()); const signal = instance.validity?.signal; cache.withdraw(Path.from("pool"), broad); cache.withdraw(path, second); - cache.announce(path, first, { ...Route.default, cost: 1n }); + cache.announce(path, first, { ...RouteInfo.default, cost: 1n }); expect(instance.validity?.signal).toBe(signal); expect(signal?.aborted).toBe(false); cache.withdraw(path, first); @@ -167,7 +167,7 @@ test("a blind selection retires on discovery while explicit instances need no pa const source = new Producer(); const held = cache.insert(path, blind, source.consume()); const owner = {}; - cache.announce(Path.from("pool"), owner, { ...Route.default, instance: Instance.random() }); + cache.announce(Path.from("pool"), owner, { ...RouteInfo.default, instance: Instance.random() }); expect(blind.validity?.signal.aborted).toBe(true); expect(cache.instance(path).validity).toBeUndefined(); cache.withdraw(Path.from("pool"), owner); diff --git a/js/net/src/consume.ts b/js/net/src/consume.ts index 3e19f1159dd..86b89c379c3 100644 --- a/js/net/src/consume.ts +++ b/js/net/src/consume.ts @@ -1,6 +1,6 @@ import type * as broadcast from "./broadcast.ts"; import { StreamCode, StreamError } from "./error.ts"; -import type { Route } from "./hop.ts"; +import type { RouteInfo } from "./hop.ts"; import * as Instance from "./instance.ts"; import { compareRouteCandidates, coveringPrefixes, Epochs } from "./internal.ts"; import type * as Path from "./path.ts"; @@ -52,13 +52,13 @@ export class BroadcastCache { Path.Valid, Map >(); - #announced = new Map>(); + #announced = new Map>(); #blind = new Map(); #blindPrefixes = new Map>(); #paths = new Map>(); /** Record this interest's live advertisement, preserving identity across route updates. */ - announce(path: Path.Valid, owner: object, route: Route, restart = false): void { + announce(path: Path.Valid, owner: object, route: RouteInfo, restart = false): void { // Only unannounced consumers covered by this advertisement lose their blind identity. for (const covered of this.#blindPrefixes.get(path) ?? []) this.#forgetBlind(covered); let entries = this.#announced.get(path); @@ -84,7 +84,7 @@ export class BroadcastCache { for (const prefix of coveringPrefixes(path)) { const entries = this.#announced.get(prefix); if (!entries) continue; - let best: { identity: object; route: Route } | undefined; + let best: { identity: object; route: RouteInfo } | undefined; const epochs = new Epochs([...entries.values()].map((entry) => entry.route)); for (const entry of entries.values()) { if (epochs.supersedes(entry.route)) continue; diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index bae555bf01f..ae66a7ea732 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -769,8 +769,7 @@ async function session(alpn: string) { connectSession({ url, transport: pair.client }), acceptSession({ transport: pair.server, url, publish: origin.consume() }), ]); - const publication = origin.createBroadcast(Path.from("archive")); - publication.announce(); + const publication = origin.route(Path.from("archive")); const broadcast = publication.broadcast; const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); // Groups 0 to 2 were published before this producer existed. diff --git a/js/net/src/goaway-requests.test.ts b/js/net/src/goaway-requests.test.ts index bc2df5b5235..fb869add6ca 100644 --- a/js/net/src/goaway-requests.test.ts +++ b/js/net/src/goaway-requests.test.ts @@ -107,9 +107,8 @@ async function handover(kind: "lite" | "ietf"): Promise { const consume = new OriginProducer(); const publish = new OriginProducer(); - const broadcastPublication = publish.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = publish.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const served: TrackProducer[] = []; let armVideo = true; @@ -299,9 +298,8 @@ async function routeDeath(kind: "lite" | "ietf", after: boolean): Promise const consume = new OriginProducer(); const publish = new OriginProducer(); - const broadcastPublication = publish.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = publish.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const served: TrackProducer[] = []; const serving = (async () => { diff --git a/js/net/src/group-id.test.ts b/js/net/src/group-id.test.ts index d025cecad53..e17c1de620d 100644 --- a/js/net/src/group-id.test.ts +++ b/js/net/src/group-id.test.ts @@ -86,12 +86,11 @@ for (const wire of WIRES) { ]); const path = Path.from("big"); - const publication = source.createBroadcast(path); - publication.announce(); + const publication = source.route(path); const datagrams = wire.datagrams ? publication.broadcast.createDatagrams("video") : undefined; const track = publication.broadcast.createTrack("video"); - const dynamic = relay.requestsRoute(path); + const dynamic = relay.routePrefix(path); const inputs: BroadcastConsumer[] = []; const forwarding = (async () => { for await (const request of dynamic.requested()) { diff --git a/js/net/src/hop.ts b/js/net/src/hop.ts index 2319ebcbfb8..d01492d599b 100644 --- a/js/net/src/hop.ts +++ b/js/net/src/hop.ts @@ -89,59 +89,48 @@ export const Cost = { }; /** - * The path a route took through the mesh and what using it costs. + * The stream a received route serves, the path it took through the mesh, and what using it + * costs: read-only facts on an announcement. Mirrors `RouteInfo` in rs/moq-net. * - * The metadata half of an advertisement: an origin `requests()` pairs it with the - * pattern it covers, a broadcast `announce()` with the broadcast's exact path, and - * an announce event carries it so consumers can read it back. + * Carried by an announce event. Applications never build one: an origin `Route` takes + * `RouteOptions`, and the origin and the relays fill in the rest. */ -export interface Route { +export interface RouteInfo { /** * The stream the route serves: routes with one instance serve one continuous sequence - * space, so a subscription resumes from one to another. Changing it on a standing - * advertisement is a restart. Always set on a route the origin delivers; given to an - * announcing handle, unset keeps the instance its route already has, a fresh random one - * minted when the handle was made. Mirrors `Route::instance` in rs/moq-net. - * - * Set one only for a publisher that continues its group sequences across restarts and - * raises {@link epoch} on each: readers stitch every route of one instance together, so - * restarting the sequences under an old instance splices unrelated groups into their tracks. - * Do not start a named instance with `~`: that marks one a relay minted (see - * {@link Instance.isMinted}), which signing refuses to bind and a catalog's instance check - * skips. The mark is not refused, since a relay forwarding a route keeps the one it received. + * space, so a subscription resumes from one to another. Always set on a route the origin + * delivers; pass it to an origin `request` to pin this stream. */ - instance?: Instance.Valid; + readonly instance?: Instance.Valid; /** * Which incarnation of {@link instance} this is: among its routes at one prefix only the - * highest epoch is eligible, cheaper or not. Never compared across instances. Ignored - * without an instance. + * highest epoch is eligible, cheaper or not. Never compared across instances. */ - epoch?: bigint; - /** The chain of hops the route has traversed, oldest first. */ - hops: Hop[]; + readonly epoch?: bigint; + /** + * The chain of hops the route has traversed, oldest first. A 0 entry is the anonymous mark; + * see {@link isAnonymous}. A route announced on this origin has none. + */ + readonly hops: readonly Hop[]; /** What pulling content via this route costs; lower wins. */ - cost: Cost; + readonly cost: Cost; /** * The token the request advertising this route carries, from `auth.add()`, or undefined * for the session's own credential. Only the session that issued it carries it, as the * token on its moq-transport PUBLISH_NAMESPACE: any other session, the inline NAMESPACE * answering a solicited SUBSCRIBE_NAMESPACE, and moq-lite advertise the route unnamed. - * Swapping it renews the request with REQUEST_UPDATE. Local: a relay never forwards it. Mirrors `Route::auth` in rs/moq-net. + * Swapping it renews the request with REQUEST_UPDATE. Local: a relay never forwards it. */ - auth?: Credential; + readonly auth?: Credential; } -/** Constructors and helpers for {@link Route}. */ -export const Route = { +/** Constructors and helpers for {@link RouteInfo}. @internal */ +export const RouteInfo = { /** An empty hop chain at zero cost: what a publisher seeds for a live broadcast. */ - default: { hops: [], cost: Cost.zero } as Route, + default: { hops: [], cost: Cost.zero } as RouteInfo, /** Fill route defaults and saturate the static price at the wire ceiling. */ - normalize( - route: - | Route - | { instance?: Instance.Valid; epoch?: bigint; hops?: readonly Hop[]; cost?: Cost; auth?: Credential } = {}, - ): Route { + normalize(route: Partial = {}): RouteInfo { const cost = route.cost ?? Cost.zero; if (typeof cost !== "bigint" || cost < 0n) throw new RangeError("route cost must be a non-negative bigint"); const max = 2n ** 62n - 1n; @@ -162,12 +151,12 @@ export const Route = { * An empty chain is a local announcement, not the anonymous mark. Ingress fills a * received empty list with the anonymous hop before yielding it. */ -export function isAnonymous(route: Route): boolean { +export function isAnonymous(route: RouteInfo): boolean { return route.hops.includes(UNKNOWN_HOP); } /** Whether two routes name the same instance, epoch, hop chain, cost, and auth. */ -export function routesEqual(a: Route | undefined, b: Route | undefined): boolean { +export function routesEqual(a: RouteInfo | undefined, b: RouteInfo | undefined): boolean { if (a === b) return true; if (!a || !b) return false; return ( diff --git a/js/net/src/ietf/connection.test.ts b/js/net/src/ietf/connection.test.ts index 3060dcb9fbd..d920b04d8e8 100644 --- a/js/net/src/ietf/connection.test.ts +++ b/js/net/src/ietf/connection.test.ts @@ -162,7 +162,7 @@ test("SUBSCRIBE_NAMESPACE gets the published namespaces", async () => { const pair = createMockTransportPair(ALPN.DRAFT_18); const control = await Stream.open(pair.server, { version }); const origin = new OriginProducer(); - origin.createBroadcast(Path.from("room")).announce(); + origin.route(Path.from("room"), { hidden: true }).announce(); const connection = new Connection({ url: new URL("https://example.com"), quic: pair.server, @@ -397,9 +397,8 @@ for (const [version, alpn] of [[Version.DRAFT_22, ALPN.DRAFT_22]] as const) { const pair = createMockTransportPair(alpn); const control = await Stream.open(pair.server, { version }); const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("video", { timescale: Timescale.MILLI }); const connection = new Connection({ url: new URL("https://example.com"), @@ -433,9 +432,8 @@ async function serving(version: IetfVersion, alpn: string) { const pair = createMockTransportPair(alpn); const control = await Stream.open(pair.server, { version }); const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("video", { timescale: Timescale.MILLI }); const connection = new Connection({ url: new URL("https://example.com"), diff --git a/js/net/src/ietf/fetch.test.ts b/js/net/src/ietf/fetch.test.ts index d74b8f768c7..a34db56c948 100644 --- a/js/net/src/ietf/fetch.test.ts +++ b/js/net/src/ietf/fetch.test.ts @@ -53,8 +53,7 @@ function serve(version: IetfVersion, grant?: Signal, priority requiresSolicitation: false, grant, }); - const publication = origin.createBroadcast(Path.from("room")); - publication.announce(); + const publication = origin.route(Path.from("room")); const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI, priority, maxAge }); const uni = pair.client.incomingUnidirectionalStreams.getReader() as ReadableStreamDefaultReader< ReadableStream @@ -487,8 +486,7 @@ test("a FETCH preserves relayed metadata and cached groups without upstream FETC for (const warm of [false, true]) { using fx = serve(version); const upstream = new OriginProducer(); - const publication = upstream.createBroadcast(Path.from("archive")); - publication.announce(); + const publication = upstream.route(Path.from("archive")); const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI }); writeGroup(track, 3n, ["3-0", "3-1"]); // lite-04 has no FETCH; lite-05 can fetch, but refuses empty subscription ranges. @@ -507,7 +505,7 @@ test("a FETCH preserves relayed metadata and cached groups without upstream FETC while (await group?.readFrame()) {} group?.close(); } - const requests = fx.origin.requestsRoute(Path.from("relayed")); + const requests = fx.origin.routePrefix(Path.from("relayed")); const cursor = requests.requested(); const requested = cursor.next(); const type = { ...range(version, at(3, 0), at(3, 0)), trackNamespace: Path.from("relayed") }; diff --git a/js/net/src/ietf/goaway.test.ts b/js/net/src/ietf/goaway.test.ts index 7ceb767ae72..480dddd5a32 100644 --- a/js/net/src/ietf/goaway.test.ts +++ b/js/net/src/ietf/goaway.test.ts @@ -235,7 +235,7 @@ for (const [version, alpn] of [ const control = await Stream.open(pair.server, { version }); await Stream.accept(pair.client, version); const origin = new OriginProducer(); - origin.createBroadcast(Path.from("room")).announce(); + origin.route(Path.from("room"), { hidden: true }).announce(); const connection = new Connection({ url: new URL("https://relay.example/"), quic: pair.server, @@ -265,7 +265,7 @@ for (const [version, alpn] of [ const control = await Stream.open(pair.server, { version }); await Stream.accept(pair.client, version); const origin = new OriginProducer(); - origin.createBroadcast(Path.from("room")).announce(); + origin.route(Path.from("room"), { hidden: true }).announce(); const connection = new Connection({ url: new URL("https://relay.example/"), quic: pair.server, diff --git a/js/net/src/ietf/join.test.ts b/js/net/src/ietf/join.test.ts index 38872a9ce63..d33b3c2df0e 100644 --- a/js/net/src/ietf/join.test.ts +++ b/js/net/src/ietf/join.test.ts @@ -589,8 +589,7 @@ async function publishing(version: IetfVersion) { server.abort(); }); - const publication = origin.createBroadcast(Path.from("room")); - publication.announce(); + const publication = origin.route(Path.from("room")); const broadcast = publication.broadcast; // Written once, before anyone subscribed, and left open: only the head can deliver it. const catalog = broadcast.createTrack("catalog.json", { timescale: Timescale.MILLI }); diff --git a/js/net/src/ietf/malformed.test.ts b/js/net/src/ietf/malformed.test.ts index 0382758948f..19bf77af8d2 100644 --- a/js/net/src/ietf/malformed.test.ts +++ b/js/net/src/ietf/malformed.test.ts @@ -57,9 +57,8 @@ async function serving(version: IetfVersion, alpn: string) { const pair = createMockTransportPair(alpn); const control = await Stream.open(pair.server, { version }); const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("video", { timescale: Timescale.MILLI }); const connection = new Connection({ url: new URL("https://example.com"), diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 5acaa91461a..a8520047281 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -42,9 +42,8 @@ import { TrackStatusOk, TrackStatusRequest } from "./track.ts"; import { ALPN, type IetfVersion, Version } from "./version.ts"; function publish(origin: OriginProducer, path: Path.Valid) { - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; return broadcast; } @@ -295,7 +294,7 @@ test("TRACK_STATUS finished at once is answered on every draft", async () => { const pair = createMockTransportPair(ALPNS[version]); const session = new NativeSession(pair.server, version, true); const { pub, origin } = publisher(pair.server, { session }); - const requests = origin.requestsRoute(Path.from("room")).requested(); + const requests = origin.routePrefix(Path.from("room")).requested(); // The FIN arrives while the broadcast still resolves. const { stream, wire, finish } = requestStream(version); @@ -341,7 +340,7 @@ test("TRACK_STATUS outside the grant is refused on every draft", async () => { const session = new NativeSession(pair.server, version, true); const grant = new Signal(nothing()); const { pub, origin } = publisher(pair.server, { session, grant }); - const requests = origin.requestsRoute(Path.from("room")).requested(); + const requests = origin.routePrefix(Path.from("room")).requested(); const outside = requestStream(version); await pub.runTrackStatusRequest(trackStatus("room"), outside.stream); @@ -368,7 +367,7 @@ test("a second GOAWAY on an unanswered SUBSCRIBE closes the session", async () = const pair = createMockTransportPair(ALPNS[version]); const session = new NativeSession(pair.server, version, true); const { pub, origin } = publisher(pair.server, { session }); - const requests = origin.requests(Path.from("room")).requested(); + const requests = origin.routePrefix(Path.from("room")).requested(); const held = requestStream(version); const task = pub.runSubscribe( @@ -426,7 +425,7 @@ test("a cancelled TRACK_STATUS releases its demand on every draft", async () => const pair = createMockTransportPair(ALPNS[version]); const session = new NativeSession(pair.server, version, true); const { pub, origin } = publisher(pair.server, { session }); - const requests = origin.requestsRoute(Path.from("room")).requested(); + const requests = origin.routePrefix(Path.from("room")).requested(); // The broadcast is still resolving: its handler never answers. const early = requestStream(version); @@ -478,7 +477,7 @@ test("a SUBSCRIBE withdrawn during setup releases its demand on every draft", as const pair = createMockTransportPair(ALPNS[version]); const session = new NativeSession(pair.server, version, true); const { pub, origin } = publisher(pair.server, { session }); - const requests = origin.requestsRoute(Path.from("room")).requested(); + const requests = origin.routePrefix(Path.from("room")).requested(); // The broadcast is still resolving: its handler never answers. const early = requestStream(version); @@ -645,7 +644,7 @@ test("reserved namespace requests get DOES_NOT_EXIST while other dot namespaces // Navigation segments cannot be published. A covering application // route still proves these reserved requests are refused before lookup. const navigation = path.split("/")[0] === "."; - const claim = navigation ? origin.requests(Path.empty()) : undefined; + const claim = navigation ? origin.routePrefix(Path.empty()) : undefined; const requested = claim?.requested().next(); const broadcast = navigation ? undefined : publish(origin, Path.from(path)); const track = broadcast?.createTrack("video", { timescale: Timescale.MILLI }); @@ -1156,7 +1155,7 @@ test("a subscription outside a covering route's claim does not hear it", async ( const pair = createMockTransportPair(ALPN.DRAFT_18); const { pub, origin } = publisher(pair.server, { requiresSolicitation: true }); const chat = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from("room/chat"))])); - const dynamic = chat.requestsRoute(Path.from("room")); + const dynamic = chat.routePrefix(Path.from("room")); const subscription = await Stream.open(pair.client, { version: VERSION }); const accepted = await Stream.accept(pair.server, VERSION); @@ -1188,8 +1187,8 @@ test("a subscription hears the best covering route its claim allows", async () = const { pub, origin } = publisher(pair.server, { requiresSolicitation: true }); const scoped = (path: string) => origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from(path))])); - const chat = scoped("room/chat").requestsRoute(Path.from("room"), { cost: 1n }); - const video = scoped("room/video").requestsRoute(Path.from("room"), { cost: 5n }); + const chat = scoped("room/chat").routePrefix(Path.from("room"), { cost: 1n }); + const video = scoped("room/video").routePrefix(Path.from("room"), { cost: 5n }); const subscription = await Stream.open(pair.client, { version: VERSION }); const accepted = await Stream.accept(pair.server, VERSION); @@ -1229,8 +1228,8 @@ test("a subscription hears a broader covering route when the narrowest cannot se }); const chat = origin .scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from("tenant/chat"))])) - .requestsRoute(Path.from("tenant")); - const broad = origin.requestsRoute(Path.empty(), { cost: 5n }); + .routePrefix(Path.from("tenant")); + const broad = origin.routePrefix(Path.empty(), { cost: 5n }); const subscription = await Stream.open(pair.client, { version: VERSION }); const accepted = await Stream.accept(pair.server, VERSION); @@ -1267,7 +1266,7 @@ test("a covering route's claim is compared relative to the served root", async ( requiresSolicitation: true, }); const chat = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from("tenant/room/chat"))])); - const dynamic = chat.requestsRoute(Path.from("tenant/room")); + const dynamic = chat.routePrefix(Path.from("tenant/room")); const subscription = await Stream.open(pair.client, { version: VERSION }); const accepted = await Stream.accept(pair.server, VERSION); @@ -1351,8 +1350,7 @@ test("a new instance at the same path clears a refusal", async () => { const pair = createMockTransportPair(ALPN.DRAFT_18); const { pub, origin } = publisher(pair.server); - const broadcast = origin.createBroadcast(Path.from("restarted")); - broadcast.announce({ instance: Instance.random() }); + const broadcast = origin.route(Path.from("restarted"), { instance: Instance.random() }); void pub.runPublishNamespaces(); @@ -1362,7 +1360,7 @@ test("a new instance at the same path clears a refusal", async () => { await declinePublishNamespace(declined, 0n); await sleep(Nano.fromMilli(Milli(SETTLE))); - broadcast.announce({ ...broadcast.route, instance: Instance.random() }); + wireOf(broadcast).update({ ...wireOf(broadcast).info, instance: Instance.random() }); const retried = await nextStream(pair.client); if (!retried) throw new Error("the new instance was never offered"); @@ -1563,18 +1561,18 @@ const OTHER: Hop = HopSchema.parse(5n); test("a price change on a held namespace is one REQUEST_UPDATE, not a withdrawal", async () => { const { clock, self, pub, origin, streams, close } = clustered(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n }); void pub.runPublishNamespaces(); const stream = await take(clock, streams); expect(await acceptClustered(stream)).toEqual({ hops: [VIA, self], cost: 4n }); - broadcast.announce({ hops: [VIA], cost: 8n }); + wireOf(broadcast).update({ hops: [VIA], cost: 8n }); expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: 8n }); await acceptPublishNamespace(stream); - broadcast.announce({ hops: [VIA], cost: 0n }); + wireOf(broadcast).update({ hops: [VIA], cost: 0n }); expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: 0n }); await acceptPublishNamespace(stream); @@ -1591,14 +1589,14 @@ test("a price change on a held namespace is one REQUEST_UPDATE, not a withdrawal test("a hop path change behind the same publisher is one REQUEST_UPDATE carrying HOP_PATH", async () => { const { clock, self, pub, origin, streams, close } = clustered(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n }); void pub.runPublishNamespaces(); const stream = await take(clock, streams); await acceptClustered(stream); - broadcast.announce({ hops: [VIA, MID], cost: 4n }); + wireOf(broadcast).update({ hops: [VIA, MID], cost: 4n }); expect(await readUpdate(stream)).toEqual({ hops: [VIA, MID, self], cost: undefined }); await acceptPublishNamespace(stream); @@ -1621,8 +1619,8 @@ test.each([ ] as const)("a solicited namespace takes %s as one NAMESPACE and no NAMESPACE_DONE", async (_, hops, cost) => { const { clock, self, pair, pub, origin, close } = clustered(true); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n }); const subscription = await Stream.open(pair.client, { version: VERSION }); const stream = await Stream.accept(pair.server, VERSION); @@ -1641,7 +1639,7 @@ test.each([ params: { cluster: { hops: [VIA, self], cost: 4n } }, }); - broadcast.announce({ hops: [...hops], cost }); + wireOf(broadcast).update({ hops: [...hops], cost }); expect(await entry()).toMatchObject({ suffix: Path.from("mine"), params: { cluster: { hops: [...hops, self], cost } }, @@ -1663,14 +1661,14 @@ test.each([ test("a first-hop change is one REQUEST_UPDATE carrying HOP_PATH, not a withdrawal", async () => { const { clock, self, pub, origin, streams, close } = clustered(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n }); void pub.runPublishNamespaces(); const stream = await take(clock, streams); await acceptClustered(stream); - broadcast.announce({ hops: [OTHER], cost: 4n }); + wireOf(broadcast).update({ hops: [OTHER], cost: 4n }); expect(await readUpdate(stream)).toEqual({ hops: [OTHER, self], cost: undefined }); await acceptPublishNamespace(stream); @@ -1685,8 +1683,8 @@ test("a first-hop change is one REQUEST_UPDATE carrying HOP_PATH, not a withdraw /** A different broadcast is not an update: it withdraws the old one and advertises again. */ function republish(origin: OriginProducer, old: BroadcastProducer) { - const next = origin.createBroadcast(Path.from("mine")); - next.announce({ hops: [VIA], cost: 4n }); + const next = origin.route(Path.from("mine"), { hidden: true }); + wireOf(next).update({ hops: [VIA], cost: 4n }); old.close(); } @@ -1750,15 +1748,15 @@ test("swapping a route's token is one REQUEST_UPDATE carrying it", async () => { const { clock, pub, origin, streams, close } = clustered(false, tokens); const { sent, restore } = carriedTokens(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n, auth: tokens.issue("first") }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n, auth: tokens.issue("first") }); void pub.runPublishNamespaces(); const stream = await take(clock, streams); await acceptClustered(stream); expect(sent).toEqual(["first"]); - broadcast.announce({ hops: [VIA], cost: 4n, auth: tokens.issue("second") }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n, auth: tokens.issue("second") }); expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: undefined }); await acceptPublishNamespace(stream); expect(sent).toEqual(["first", "second"]); @@ -1775,13 +1773,13 @@ test("a foreign route token is not carried", async () => { const { clock, pub, origin, streams, close } = clustered(false, new Tokens()); const { sent, restore } = carriedTokens(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n, auth: foreign.issue("first") }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n, auth: foreign.issue("first") }); void pub.runPublishNamespaces(); const stream = await take(clock, streams); await acceptClustered(stream); - broadcast.announce({ hops: [VIA], cost: 4n, auth: foreign.issue("second") }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n, auth: foreign.issue("second") }); const more = watch(stream.reader.u53()); await clock.advance(Nano.zero); expect(more.state).toBe("pending"); @@ -1798,13 +1796,13 @@ test("naming a token on an unnamed request makes it again", async () => { const { clock, pub, origin, streams, close } = clustered(false, tokens); const { sent, restore } = carriedTokens(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n }); void pub.runPublishNamespaces(); const old = await take(clock, streams); await acceptClustered(old); - broadcast.announce({ hops: [VIA], cost: 4n, auth: tokens.issue("first") }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n, auth: tokens.issue("first") }); expect(await old.reader.done().catch(error)).toMatchObject({ code: StreamCode.Cancel }); await acceptClustered(await take(clock, streams)); @@ -1821,9 +1819,9 @@ test("closing a route's token makes its request again without it", async () => { const { clock, pub, origin, streams, close } = clustered(false, tokens); const { sent, restore } = carriedTokens(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); const token = tokens.issue("first"); - broadcast.announce({ hops: [VIA], cost: 4n, auth: token }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n, auth: token }); void pub.runPublishNamespaces(); const old = await take(clock, streams); @@ -1842,9 +1840,9 @@ test("closing a route's token makes its request again without it", async () => { test("a republish withdraws the PUBLISH_NAMESPACE and advertises again", async () => { const { clock, pub, origin, streams, close } = clustered(); try { - const broadcastPublication = origin.createBroadcast(Path.from("mine")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce({ hops: [VIA], cost: 4n }); + const broadcastRoute = origin.route(Path.from("mine"), { hidden: true }); + const broadcast = broadcastRoute.broadcast; + wireOf(broadcastRoute).update({ hops: [VIA], cost: 4n }); void pub.runPublishNamespaces(); const old = await take(clock, streams); @@ -1864,9 +1862,9 @@ test("a republish withdraws the PUBLISH_NAMESPACE and advertises again", async ( test("a republish withdraws the solicited NAMESPACE and sends it again", async () => { const { pair, pub, origin, close } = clustered(true); try { - const broadcastPublication = origin.createBroadcast(Path.from("mine")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce({ hops: [VIA], cost: 4n }); + const broadcastRoute = origin.route(Path.from("mine"), { hidden: true }); + const broadcast = broadcastRoute.broadcast; + wireOf(broadcastRoute).update({ hops: [VIA], cost: 4n }); const subscription = await Stream.open(pair.client, { version: VERSION }); const stream = await Stream.accept(pair.server, VERSION); @@ -1903,14 +1901,14 @@ test.each([ ])("a refused update %s", async (_, retryInterval) => { const { clock, pub, origin, streams, close } = clustered(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n }); void pub.runPublishNamespaces(); const stream = await take(clock, streams); await acceptClustered(stream); - broadcast.announce({ hops: [VIA], cost: 8n }); + wireOf(broadcast).update({ hops: [VIA], cost: 8n }); await readUpdate(stream); await declinePublishNamespace(stream, retryInterval); @@ -1944,8 +1942,8 @@ test.each([ test("a refused update whose peer closes the request keeps the loop running", async () => { const { clock, pub, origin, streams, close } = clustered(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n }); let failed: unknown; void pub.runPublishNamespaces().catch((err: unknown) => { failed = err; @@ -1954,7 +1952,7 @@ test("a refused update whose peer closes the request keeps the loop running", as const stream = await take(clock, streams); await acceptClustered(stream); - broadcast.announce({ hops: [VIA], cost: 8n }); + wireOf(broadcast).update({ hops: [VIA], cost: 8n }); await readUpdate(stream); await declinePublishNamespace(stream, 1n); stream.close(); @@ -1975,17 +1973,17 @@ test("a refused update whose peer closes the request keeps the loop running", as test("a change while an update is unanswered waits for its answer", async () => { const { clock, pub, origin, streams, close } = clustered(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n }); void pub.runPublishNamespaces(); const stream = await take(clock, streams); await acceptClustered(stream); - broadcast.announce({ hops: [VIA], cost: 8n }); + wireOf(broadcast).update({ hops: [VIA], cost: 8n }); expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: 8n }); - broadcast.announce({ hops: [VIA], cost: 12n }); + wireOf(broadcast).update({ hops: [VIA], cost: 12n }); const second = watch(stream.reader.u53()); await clock.advance(Nano.fromMilli(Milli(1_000))); expect(second.state).toBe("pending"); @@ -2013,7 +2011,7 @@ test("a change while an update is unanswered waits for its answer", async () => test("an advertisement the peer keeps ending comes back on a growing backoff", async () => { const { clock, pub, origin, streams, close } = clustered(); try { - origin.createBroadcast(Path.from("mine")).announce({ hops: [VIA], cost: 4n }); + wireOf(origin.route(Path.from("mine"), { hidden: true })).update({ hops: [VIA], cost: 4n }); void pub.runPublishNamespaces(); let stream = await take(clock, streams); @@ -2041,14 +2039,14 @@ test("an advertisement the peer keeps ending comes back on a growing backoff", a test("an unanswered update drops the request and re-offers the namespace fresh", async () => { const { clock, pub, origin, streams, close } = clustered(); try { - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [VIA], cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { hidden: true }); + wireOf(broadcast).update({ hops: [VIA], cost: 4n }); void pub.runPublishNamespaces(); const stream = await take(clock, streams); await acceptClustered(stream); - broadcast.announce({ hops: [VIA], cost: 8n }); + wireOf(broadcast).update({ hops: [VIA], cost: 8n }); await readUpdate(stream); const reset = watch(stream.reader.u53()); @@ -2079,8 +2077,7 @@ test.each([ const self: Hop = HopSchema.parse(7n); const pair = createMockTransportPair(ALPN.DRAFT_18); const { pub, origin } = publisher(pair.server, { cluster: { self, peer } }); - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ cost: 4n }); + const broadcast = origin.route(Path.from("mine"), { cost: 4n }); void pub.runPublishNamespaces(); const stream = await nextStream(pair.client); @@ -2090,7 +2087,7 @@ test.each([ expect(msg.trackNamespace).toBe(Path.from("mine")); await acceptPublishNamespace(stream); - broadcast.announce({ cost: peer === undefined ? 8n : 4n }); + broadcast.setCost(peer === undefined ? 8n : 4n); await noStream(pair.client, clock); origin.close(); diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 55034c0c5c3..7e7d2c25fbc 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -19,7 +19,7 @@ import { unauthorized, } from "../error.ts"; import type * as group from "../group.ts"; -import type { Hop, Route } from "../hop.ts"; +import type { Hop, RouteInfo } from "../hop.ts"; import { finalSequence, firstEligible, hiddenBelow, hooks, presented, type ReadGroupFrame } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; @@ -79,7 +79,7 @@ const RETRY_BASE = 100; const RETRY_MAX = 5000; /** Cluster parameters for one snapshot: the advertised hops, then our own id last. */ -function clusterFor(base: Cluster.Advert | undefined, route: Route): Cluster.Advert | undefined { +function clusterFor(base: Cluster.Advert | undefined, route: RouteInfo): Cluster.Advert | undefined { if (!base) return undefined; const self = base.hops.at(-1); if (self === undefined) return undefined; @@ -1819,7 +1819,7 @@ export class Publisher { /** * The extension parameters an advertisement of `route` carries. */ - #params(route: Route): AdvertParams { + #params(route: RouteInfo): AdvertParams { return { cluster: clusterFor(this.#advert, route) }; } @@ -1828,7 +1828,7 @@ export class Publisher { * is logged and skipped: a peer that wants none of this rejects each one and stays * connected. */ - async #advertise(path: Path.Valid, requests: Requests, route: Route): Promise { + async #advertise(path: Path.Valid, requests: Requests, route: RouteInfo): Promise { const params = this.#params(route); const auth = this.#carry(route.auth); const requestId = await this.#session.nextRequestId(); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 7333b0b493f..1a5dc4918f3 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -21,7 +21,7 @@ import { } from "../error.ts"; import { type Fill, fillChanged, type Requests, wantedRuns } from "../fill.ts"; import type * as netGroup from "../group.ts"; -import { Cost, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; +import { Cost, type RouteInfo, routesEqual, UNKNOWN_HOP } from "../hop.ts"; import * as Instance from "../instance.ts"; import { finalSequence, hiddenBelow, hooks, maxDelayOf, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import type { Lister } from "../listing.ts"; @@ -119,7 +119,7 @@ type SubscribeSetupState = { }; /** An announced path: each live advertisement referencing it, oldest first, and the route it holds. */ -type Announced = { adverts: { id: number; route: Route }[]; route: Route }; +type Announced = { adverts: { id: number; route: RouteInfo }[]; route: RouteInfo }; /** A local announce reader's filter: its scope, the prefix it asked for, and its hidden opt-in. */ type Filter = { scope: Path.Pattern; prefix: Path.Valid; hidden: boolean; covering: boolean }; @@ -266,7 +266,7 @@ export class Subscriber { } // What a route costs once the peer has asked us to leave. - #priced(route: Route): Route { + #priced(route: RouteInfo): RouteInfo { if (!this.#goingAway()) return route; if (route.cost === DRAIN_COST) return route; return { ...route, cost: DRAIN_COST }; @@ -300,7 +300,7 @@ export class Subscriber { /** * The route an advertisement carries, before it is minted an instance; one without a path is anonymous and free. */ - #route({ cluster }: AdvertParams): Route { + #route({ cluster }: AdvertParams): RouteInfo { return cluster === undefined ? { hops: [UNKNOWN_HOP], cost: Cost.zero } : { ...cluster }; } @@ -370,7 +370,7 @@ export class Subscriber { * Record one more advertisement for a path, returning the id that names it. Consumers * hear `start` for the first; a later one stands as the newest (see `#settleAnnounce`). */ - #attachAnnounce(path: Path.Valid, route: Route): number { + #attachAnnounce(path: Path.Valid, route: RouteInfo): number { const id = this.#nextAdvert++; const existing = this.#announced.get(path); if (existing) { @@ -396,7 +396,7 @@ export class Subscriber { } /** Replace the route of advertisement `id`, which moves the path only while it is the newest. */ - #updateAnnounce(path: Path.Valid, id: number, route: Route) { + #updateAnnounce(path: Path.Valid, id: number, route: RouteInfo) { const existing = this.#announced.get(path); const advert = existing?.adverts.find((advert) => advert.id === id); if (existing === undefined || advert === undefined) return; diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 68469b293d7..3808ed63d56 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -33,9 +33,8 @@ import { withTimeout } from "./util/timeout.ts"; import { wireOf } from "./wire.ts"; function publish(origin: OriginProducer, path: Path.Valid) { - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; return broadcast; } @@ -891,10 +890,9 @@ test("integration: a peer is served the cheaper route it was offered, not the lo const path = Path.from("test"); // One publisher instance, so the two compete on cost alone. const instance = Instance.random(); - const localPublication = origin.createBroadcast(path); - const local = localPublication.broadcast; - localPublication.announce({ instance, cost: 5n }); - const dynamic = origin.requestsRoute(path, { instance, cost: 1n }); + const localRoute = origin.route(path, { instance, cost: 5n }); + const local = localRoute.broadcast; + const dynamic = origin.routePrefix(path, { instance, cost: 1n }); const [client, server] = await Promise.all([ connect(url, { transport: pair.client }), @@ -1264,8 +1262,7 @@ test("integration: ietf fetches a past group of a finished track", async () => { for (const protocol of [Ietf.ALPN.DRAFT_18, Ietf.ALPN.DRAFT_20, Ietf.ALPN.DRAFT_22]) { const pair = createMockTransportPair(protocol); const origin = new OriginProducer(); - const publication = origin.createBroadcast(Path.from("test")); - publication.announce(); + const publication = origin.route(Path.from("test")); // No publisher limit, so the superseded group stays fresh to fetch, and no MAX_CACHE_DURATION. const published = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); for (let sequence = 0; sequence < 3; sequence++) { @@ -2617,12 +2614,12 @@ test("create then announce is discoverable on the wire", async () => { ]); const announced = client.routes(); - const broadcastPublication = origin.createBroadcast(Path.from("later")); - const broadcast = broadcastPublication.broadcast; + const broadcastRoute = origin.route(Path.from("later"), { hidden: true }); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("chat", { timescale: Timescale.MILLI }); const pending = announced.next(); - broadcastPublication.announce(); + broadcastRoute.announce(); const entry = await pending; expect(entry?.prefix).toBe("later" as Path.Valid); expect(entry?.kind).toBe("start"); @@ -2640,7 +2637,7 @@ test.each([Lite.ALPN_06, Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_18, Ietf.ALPN.DRAFT_2 const pair = createMockTransportPair(protocol); const origin = new OriginProducer(); const consumer = new OriginProducer(); - const handle = origin.requests(Path.empty()); + const handle = origin.routePrefix(Path.empty()); const held = new BroadcastProducer(); held.createTrack("chat", { timescale: Timescale.MILLI }).writeFrame(textFrame("hello")); const serving = (async () => { @@ -2674,14 +2671,15 @@ test.each([Lite.ALPN_06, Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_18, Ietf.ALPN.DRAFT_2 const pair = createMockTransportPair(protocol); const origin = new OriginProducer(); const consumer = new OriginProducer(); - const handle = origin.requests(Path.empty()); + const handle = origin.routePrefix(Path.empty()); const serving = (async () => { const requests = handle.requested(); const request = (await requests.next()).value; if (!request) throw new Error("missing job request"); - const prepared = request.prepare(); - prepared.broadcast.createTrack("chat", { timescale: Timescale.MILLI }).writeFrame(textFrame("job")); - return prepared.publish(); + const job = request.route({ hidden: true }); + job.broadcast.createTrack("chat", { timescale: Timescale.MILLI }).writeFrame(textFrame("job")); + job.announce(); + return job; })(); const [client, server] = await Promise.all([ connect(url, { transport: pair.client, consume: consumer }), @@ -2692,11 +2690,11 @@ test.each([Lite.ALPN_06, Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_18, Ietf.ALPN.DRAFT_2 if (!remote) throw new Error("request did not resolve"); const track = remote.track("chat").subscribe().ordered(); await expect(track.readString()).rejects.toBeInstanceOf(Error); - const publication = await serving; + const job = await serving; track.close(); requested.close(); handle.close(); - publication.broadcast.close(); + job.close(); client.abort(); server.abort(); origin.close(); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 6b1c48be47f..4d1c81d4587 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -12,7 +12,7 @@ import type * as datagram from "./datagram.ts"; import type { Delivered } from "./delivered.ts"; import { toStreamCode } from "./error.ts"; import type { Frame, FrameConsumer, Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; -import { isAnonymous, type Route } from "./hop.ts"; +import { isAnonymous, type RouteInfo } from "./hop.ts"; import type * as Instance from "./instance.ts"; import * as Path from "./path.ts"; import type { Timestamp } from "./time.ts"; @@ -132,12 +132,12 @@ export function presented( * candidate supersedes. Supersession is decided among what the reader may see, so a higher epoch * it cannot see never hides a route it can. */ -export function firstEligible( +export function firstEligible( candidates: readonly T[], admits: (candidate: T) => boolean = () => true, ): T | undefined { const admitted = candidates.filter(admits); - const byPrefix = new Map(); + const byPrefix = new Map(); for (const candidate of admitted) { const routes = byPrefix.get(candidate.prefix); if (routes) routes.push(candidate.route); @@ -728,12 +728,6 @@ export const hooks: { * mirror is released too: not when its group reads on, or may yet, from another copy. */ evictGroup: (group: GroupConsumer) => boolean; - /** Attach the origin advertisement of a created broadcast. */ - attachAnnouncer: ( - producer: BroadcastProducer, - announcer: { announce(route: Route): void; unannounce(): void; route(): Route | undefined }, - ) => void; - /** Call `fn` synchronously when an open broadcast closes, from any handle. */ onClosed: (producer: BroadcastProducer, fn: () => void) => Dispose; /** Name a broadcast handle by the path an origin created or resolved it at. */ @@ -1012,10 +1006,6 @@ export const hooks: { evictGroup: () => { throw new Error("group.ts not loaded"); }, - attachAnnouncer: () => { - throw new Error("broadcast.ts not loaded"); - }, - onClosed: () => { throw new Error("broadcast.ts not loaded"); }, @@ -1083,7 +1073,7 @@ export function* coveringPrefixes(path: Path.Valid): Generator { * a higher epoch at the same prefix. An older incarnation of an instance is never eligible, * however cheap, since its publisher was replaced. */ -export function superseded(route: Route, others: Iterable): boolean { +export function superseded(route: RouteInfo, others: Iterable): boolean { return new Epochs(others).supersedes(route); } @@ -1095,7 +1085,7 @@ export function superseded(route: Route, others: Iterable): boolean { export class Epochs { readonly #highest = new Map(); - constructor(routes: Iterable) { + constructor(routes: Iterable) { for (const route of routes) { const epoch = route.epoch ?? 0n; if (epoch === 0n) continue; @@ -1105,14 +1095,14 @@ export class Epochs { } /** Whether a route carries `route`'s instance at a higher epoch. */ - supersedes(route: Route): boolean { + supersedes(route: RouteInfo): boolean { const highest = this.#highest.get(route.instance); return highest !== undefined && highest > (route.epoch ?? 0n); } } /** Prefer identified publishers, then lower static cost. */ -export function compareRoutes(a: Route, b: Route): number { +export function compareRoutes(a: RouteInfo, b: RouteInfo): number { return Number(isAnonymous(a)) - Number(isAnonymous(b)) || (a.cost < b.cost ? -1 : a.cost > b.cost ? 1 : 0); } @@ -1124,7 +1114,7 @@ export function compareRoutes(a: Route, b: Route): number { * matching `route_order` in rs/moq-net for routes a node did not get from a cluster peer, which * is every route here. */ -export function compareRouteCandidates(path: Path.Valid, prefix: Path.Valid, a: Route, b: Route): number { +export function compareRouteCandidates(path: Path.Valid, prefix: Path.Valid, a: RouteInfo, b: RouteInfo): number { const order = compareRoutes(a, b) || a.hops.length - b.hops.length; if (order !== 0 || path === prefix) return order; const ha = spreadHash(path, a.instance ?? ""); diff --git a/js/net/src/lite/compression.test.ts b/js/net/src/lite/compression.test.ts index 43d7d1c9a41..d6d32fb03f8 100644 --- a/js/net/src/lite/compression.test.ts +++ b/js/net/src/lite/compression.test.ts @@ -13,11 +13,11 @@ for (const downstream of [ALPN_06, ALPN_07_WIP]) { const installed = clock.install(); const source = new Producer(); const destination = new Producer(); - const broadcastPublication = source.createBroadcast(Path.from("compressed")); - const broadcast = broadcastPublication.broadcast; + const broadcastRoute = source.route(Path.from("compressed"), { hidden: true }); + const broadcast = broadcastRoute.broadcast; const datagrams = broadcast.createDatagrams("data"); const track = broadcast.createTrack("data", { compress: true }); - broadcastPublication.announce(); + broadcastRoute.announce(); const peers: { abort(): void }[] = []; async function link(publish: Producer, consume: Producer, alpn: string) { const pair = createMockTransportPair(alpn); diff --git a/js/net/src/lite/connection.test.ts b/js/net/src/lite/connection.test.ts index 48690d2f88c..a59006e6042 100644 --- a/js/net/src/lite/connection.test.ts +++ b/js/net/src/lite/connection.test.ts @@ -309,9 +309,8 @@ for (const [alpn, version] of [ const pair = createMockTransportPair(alpn); const fin = holdFins(pair.server, "uni"); const origin = new Producer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const url = new URL("https://localhost/test"); const client = new Connection({ url, quic: pair.client, version }); @@ -371,9 +370,8 @@ for (const [alpn, version] of [ deliverWhole(pair.client); if (overtaken === "fin") finAfterClose(pair.client); const origin = new Producer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const url = new URL("https://localhost/test"); const client = new Connection({ url, quic: pair.client, version }); @@ -423,9 +421,8 @@ for (const [alpn, version] of [ const pair = createMockTransportPair(alpn); finAfterClose(pair.client); const origin = new Producer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const url = new URL("https://localhost/test"); const client = new Connection({ url, quic: pair.client, version }); @@ -468,9 +465,8 @@ for (const [alpn, version] of [ test(`a peer close finishes a FIN'd track over qmux ${versionName(version)}`, async () => { const pair = qmuxPair(); const origin = new Producer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const url = new URL("https://localhost/test"); const client = new Connection({ url, quic: pair.client, version }); @@ -509,9 +505,8 @@ for (const [alpn, version] of [ async function servedRawSubscription(alpn: string = ALPN_07_WIP, version: Version = Version.DRAFT_07) { const pair = createMockTransportPair(alpn); const origin = new Producer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const server = new Connection({ url: new URL("https://relay.example/"), @@ -628,9 +623,8 @@ test("close waits for a served FETCH to be acknowledged", async () => { const pair = createMockTransportPair(ALPN_05); const fin = holdFins(pair.server, "incoming-bidi"); const origin = new Producer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = producer.appendGroup(); group.writeFrame(textFrame("last")); @@ -681,9 +675,8 @@ test("close waits for a request served while withdrawals are in flight", async ( const fin = holdFins(pair.server, "incoming-bidi"); const source = new Producer(); const destination = new Producer(); - const broadcastPublication = source.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = source.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = producer.appendGroup(); group.writeFrame(textFrame("last")); diff --git a/js/net/src/lite/copy_fill.test.ts b/js/net/src/lite/copy_fill.test.ts index 68bf496cd99..48f282ee605 100644 --- a/js/net/src/lite/copy_fill.test.ts +++ b/js/net/src/lite/copy_fill.test.ts @@ -28,8 +28,7 @@ async function peers(alpn: string) { connectSession({ url, transport: pair.client }), acceptSession({ transport: pair.server, url, publish: origin.consume() }), ]); - const publication = origin.createBroadcast(Path.from("room")); - publication.announce(); + const publication = origin.route(Path.from("room")); const broadcast = publication.broadcast; const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const requests = track.requests(); @@ -238,8 +237,7 @@ test("copy fill: a filled group stops downloading once every reader left or pass connectSession({ url, transport: pair.client }), acceptSession({ transport: pair.server, url, publish: origin.consume() }), ]); - const publication = origin.createBroadcast(Path.from("room")); - publication.announce(); + const publication = origin.route(Path.from("room")); const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); write(track.createGroup(1n), 1n, "live"); // The archive answers group 0 with one frame and keeps it open. @@ -304,8 +302,7 @@ test("copy fill: a filled group nobody holds any more stops downloading", async connectSession({ url, transport: pair.client }), acceptSession({ transport: pair.server, url, publish: origin.consume() }), ]); - const publication = origin.createBroadcast(Path.from("room")); - publication.announce(); + const publication = origin.route(Path.from("room")); const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); write(track.createGroup(1n), 1n, "live"); // The archive answers group 0 with one frame and never finishes it. diff --git a/js/net/src/lite/datagram-tracks.test.ts b/js/net/src/lite/datagram-tracks.test.ts index c5138d7c0f3..88d167a49fa 100644 --- a/js/net/src/lite/datagram-tracks.test.ts +++ b/js/net/src/lite/datagram-tracks.test.ts @@ -15,7 +15,7 @@ for (const alpn of [ALPN_05, ALPN_06, ALPN_07_WIP]) { for (const streams of [false, true]) { test(`${alpn}: ${streams ? "same-name kinds" : "datagram-only track"} delivery`, async () => { const source = new Origin(); - const publication = source.createBroadcast(path); + const publication = source.route(path, { hidden: true }); const datagrams = publication.broadcast.createDatagrams("audio", { timescale: Timescale.MICRO, priority: -7, @@ -104,7 +104,7 @@ test("lite-04 refuses datagram tracks at setup", async () => { test("lite-07 bounds and prioritizes independent createWritable datagram queues", async () => { const source = new Origin(); - const publication = source.createBroadcast(path); + const publication = source.route(path, { hidden: true }); const datagrams = publication.broadcast.createDatagrams("audio"); publication.broadcast.createTrack("audio", { compress: true }); publication.announce(); @@ -155,7 +155,7 @@ for (const alpn of [ALPN_05, ALPN_06]) for (const first of ["stream", "datagram"]) { test(`${alpn}: datagram readers rejoin and outlive streams (${first} first)`, async () => { const source = new Origin(); - const publication = source.createBroadcast(path); + const publication = source.route(path, { hidden: true }); const datagrams = publication.broadcast.createDatagrams("audio"); const track = publication.broadcast.createTrack("audio"); publication.announce(); @@ -200,7 +200,7 @@ for (const alpn of [ALPN_05, ALPN_06]) test("lite-07 forwards a priority change made while the previous DATAGRAMS_UPDATE writes", async () => { const source = new Origin(); - const publication = source.createBroadcast(path); + const publication = source.route(path, { hidden: true }); const datagrams = publication.broadcast.createDatagrams("audio"); publication.announce(); const pair = createMockTransportPair(ALPN_07_WIP); @@ -231,7 +231,7 @@ test("lite-07 forwards a priority change made while the previous DATAGRAMS_UPDAT test("lite-06: a request cancelled behind the shared datagram writer sends nothing", async () => { const source = new Origin(); - const publication = source.createBroadcast(path); + const publication = source.route(path, { hidden: true }); const first = publication.broadcast.createDatagrams("a"); const second = publication.broadcast.createDatagrams("b"); publication.announce(); diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index f2aa0d241e9..eae0748cf2f 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -32,9 +32,8 @@ import { Track as TrackMessage } from "./track.ts"; import { ALPN_05, ALPN_06, ALPN_07_WIP, hasRanges, keepsSubscribeOpen, Version } from "./version.ts"; function publish(origin: OriginProducer, path: Path.Valid) { - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; return broadcast; } @@ -116,9 +115,8 @@ test.each([ const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("cam")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce({ cost: 7n }); + const broadcastRoute = origin.route(Path.from("cam"), { cost: 7n }); + const broadcast = broadcastRoute.broadcast; const written: Uint8Array[] = []; const stream = new Stream({ @@ -136,7 +134,7 @@ test.each([ const initial = written.length; expect(initial).toBeGreaterThan(0); - broadcastPublication.announce({ cost: 9n }); + broadcastRoute.setCost(9n); await settle(); expect(written.length > initial).toBe(sent); @@ -734,7 +732,7 @@ async function servedSubscription( broadcast = new BroadcastProducer(); const front = new Front(); front.serve(broadcast.consume()); - const dynamic = origin.requestsRoute(Path.from("test")); + const dynamic = origin.routePrefix(Path.from("test")); void (async () => { for await (const request of dynamic.requested()) request.serve(front.consumer); })(); @@ -2831,9 +2829,8 @@ test("lite draft-06: announces wait for the setup grant", async () => { answered = resolve; }); const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), origin.consume(), { grant, ready }); - const broadcastPublication = origin.createBroadcast(Path.from("foo/bar")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("foo/bar")); + const broadcast = broadcastRoute.broadcast; const written: Uint8Array[] = []; const stream = new Stream({ @@ -2909,7 +2906,7 @@ test("lite draft-06: closing while announces wait for the setup grant does not h test("lite draft-06: a grant that shrinks while a TRACK resolves refuses it", async () => { const pair = createMockTransportPair(ALPN_06); const origin = new OriginProducer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const requests = handle.requested(); const grant = new Signal(grantOf("live")); const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), origin.consume(), { @@ -2950,7 +2947,7 @@ test("lite draft-06: a grant that shrinks while a TRACK resolves refuses it", as test("lite draft-06: a grant that shrinks while TRACK_INFO is blocked resets it", async () => { const pair = createMockTransportPair(ALPN_06); const origin = new OriginProducer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const requests = handle.requested(); const grant = new Signal(grantOf("live")); const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), origin.consume(), { @@ -3013,7 +3010,7 @@ test("lite draft-06: a grant that shrinks while TRACK_INFO is blocked resets it" test("lite draft-06: a grant that shrinks while the broadcast resolves resets the subscription", async () => { const pair = createMockTransportPair(ALPN_06); const origin = new OriginProducer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const requests = handle.requested(); const grant = new Signal(grantOf("live")); const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), origin.consume(), { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 8210e0b0115..4e75c4430c3 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -19,7 +19,7 @@ import { unauthorized, } from "../error.ts"; import type * as group from "../group.ts"; -import { Cost, type Hop, type Route, routesEqual } from "../hop.ts"; +import { Cost, type Hop, type RouteInfo, routesEqual } from "../hop.ts"; import { finalSequence, hiddenBelow, hooks, insertRun, presented, type Run, runGaps } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; @@ -601,15 +601,15 @@ export class Publisher { let nextAnnounceId = 0n; const announceIds = new Map(); - const wireHops = (route: Route): Hop[] => { - if (hasAnnounceOk(this.version)) return route.hops; + const wireHops = (route: RouteInfo): Hop[] => { + if (hasAnnounceOk(this.version)) return [...route.hops]; return [...route.hops, this.hop]; }; // What the peer decodes for a route: pre-lite-06 wires carry no cost, so a re-price // there must not restart. // moq-lite carries no per-request auth, so a swap alone sends nothing. - const onWire = (route: Route): Route => ({ + const onWire = (route: RouteInfo): RouteInfo => ({ ...route, cost: hasRouteCost(this.version) ? route.cost : Cost.zero, auth: undefined, @@ -621,7 +621,7 @@ export class Publisher { !sameInstance(prev, next) || (hasInstance(this.version) && (prev.route.epoch ?? 0n) !== (next.route.epoch ?? 0n)); - const announce = async (suffix: Path.Valid, route: Route) => { + const announce = async (suffix: Path.Valid, route: RouteInfo) => { console.debug(`announce: broadcast=${suffix} active=true instance=${route.instance}`); if (hasAnnounceId(this.version)) announceIds.set(suffix, nextAnnounceId++); await encodeAnnounceBroadcast( @@ -638,7 +638,7 @@ export class Publisher { ); }; - const update = async (suffix: Path.Valid, route: Route) => { + const update = async (suffix: Path.Valid, route: RouteInfo) => { if (!hasAnnounceId(this.version)) { await retract(suffix); await announce(suffix, route); @@ -658,7 +658,7 @@ export class Publisher { }; // Another instance or epoch: ANNOUNCE_RESTART on lite-07, an end and a start before it. - const restart = async (suffix: Path.Valid, route: Route) => { + const restart = async (suffix: Path.Valid, route: RouteInfo) => { const id = announceIds.get(suffix); if (id === undefined || !hasAnnounceRestart(this.version)) { await retract(suffix); diff --git a/js/net/src/lite/refresh.test.ts b/js/net/src/lite/refresh.test.ts index 90e2ad341a0..15378a82123 100644 --- a/js/net/src/lite/refresh.test.ts +++ b/js/net/src/lite/refresh.test.ts @@ -13,9 +13,8 @@ test.each([ALPN_06, ALPN_07_WIP])("refresh joins reach a browser publisher on %s const installed = clock.install(); const source = new Producer(); const b = new Producer(); - const broadcastPublication = source.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = source.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("data", { refresh: 1 }); const pair = createMockTransportPair(alpn); const url = new URL("https://localhost/refresh"); diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index a9004ee48f2..b31106e1ae7 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -17,7 +17,7 @@ import { TimestampMismatch, } from "../error.ts"; import type { Consumer as GroupConsumer } from "../group.ts"; -import { HopSchema, isAnonymous, MAX_HOPS, Route, UNKNOWN_HOP } from "../hop.ts"; +import { HopSchema, isAnonymous, MAX_HOPS, RouteInfo, UNKNOWN_HOP } from "../hop.ts"; import * as Instance from "../instance.ts"; import { hooks } from "../internal.ts"; import { GRACE } from "../ledger.ts"; @@ -201,8 +201,8 @@ test("an announce consumer closed while its stream opens sends nothing on it", a }); test("a local empty hop chain is not anonymous", () => { - expect(isAnonymous(Route.default)).toBe(false); - expect(isAnonymous({ hops: [UNKNOWN_HOP], cost: Route.default.cost })).toBe(true); + expect(isAnonymous(RouteInfo.default)).toBe(false); + expect(isAnonymous({ hops: [UNKNOWN_HOP], cost: RouteInfo.default.cost })).toBe(true); }); test("a max-length chain plus withheld responder is dropped", async () => { diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 7c6fb03d36c..afdd4067d43 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -21,7 +21,7 @@ import { unauthorized, } from "../error.ts"; import * as netGroup from "../group.ts"; -import { Cost, type Hop, MAX_HOPS, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; +import { Cost, type Hop, MAX_HOPS, type RouteInfo, routesEqual, UNKNOWN_HOP } from "../hop.ts"; import * as Instance from "../instance.ts"; import { hiddenBelow, hooks, maxDelayOf, minDelayOf, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import type { Lister } from "../listing.ts"; @@ -409,7 +409,7 @@ export class Subscriber { // retract that one's state. type Advertisement = { live: boolean; - route: Route; + route: RouteInfo; captures: Path.Pattern[] | undefined; }; // Each holds one of the session's announce slots, reflected and hidden ones included. @@ -721,7 +721,7 @@ export class Subscriber { }); continue; } - const route: Route = { instance, epoch, hops: fullHops, cost: this.#cost(cost) }; + const route: RouteInfo = { instance, epoch, hops: fullHops, cost: this.#cost(cost) }; const captures = scopeCaptures(scope, path); if (!visible(path)) { advertised.set(path, { live: false, route, captures }); diff --git a/js/net/src/lite/track_stream.test.ts b/js/net/src/lite/track_stream.test.ts index cb396508eb3..3ef3a0341f4 100644 --- a/js/net/src/lite/track_stream.test.ts +++ b/js/net/src/lite/track_stream.test.ts @@ -117,9 +117,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; let producer: TrackProducer | undefined; const serving = (async () => { for (;;) { @@ -155,9 +154,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver const closing = spyOn(pair.server, "close"); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const client = await Stream.open(pair.client, { version }); const server = await Stream.accept(pair.server, version); @@ -179,9 +177,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; let producer: TrackProducer | undefined; const serving = (async () => { for (;;) { @@ -227,9 +224,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producers: TrackProducer[] = []; const serving = (async () => { for (;;) { @@ -269,9 +265,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const producers: TrackProducer[] = []; const serving = (async () => { for (;;) { @@ -328,9 +323,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; // Answered by hand, once every requester has left. const requested = wireOf(broadcast).requested(); @@ -356,9 +350,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const requested = wireOf(broadcast).requested(); await requester(pair, publisher, kind); @@ -379,9 +372,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; // Answered by hand, after the first TRACK stream has left. const requested = wireOf(broadcast).requested(); @@ -410,9 +402,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const serving = (async () => { for (;;) { const request = await wireOf(broadcast).requested(); diff --git a/js/net/src/lite/tracks.test.ts b/js/net/src/lite/tracks.test.ts index 346abbbe2f7..cd3beebc5ab 100644 --- a/js/net/src/lite/tracks.test.ts +++ b/js/net/src/lite/tracks.test.ts @@ -350,9 +350,8 @@ function publisher(origin: OriginProducer) { test("data after a TRACKS request closes the session", async () => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("a"); const { list, closing } = publisher(origin); const listing = await list("room"); @@ -366,9 +365,8 @@ test("data after a TRACKS request closes the session", async () => { test("a publisher lists its broadcast's own tracks, never one served on request", async () => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("a", { priority: 5 }); // Served on request: answered when asked, never listed. void wireOf(broadcast) @@ -389,9 +387,8 @@ test("a publisher lists its broadcast's own tracks, never one served on request" test("a newer listing of a broadcast on one session replaces the older", async () => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("a"); const { list } = publisher(origin); const older = await list("room"); @@ -408,7 +405,7 @@ test("a newer listing of a broadcast on one session replaces the older", async ( test("a path served through a covering prefix route is NOT_FOUND", async () => { const origin = new OriginProducer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); void (async () => { for await (const request of dynamic.requested()) { const served = new BroadcastProducer(); @@ -425,7 +422,7 @@ test("a path served through a covering prefix route is NOT_FOUND", async () => { test("a local read through a covering prefix route is NOT_FOUND, and through its exact route lists", async () => { const origin = new OriginProducer(); for (const prefix of ["room", "room/bob"]) { - const dynamic = origin.requestsRoute(Path.from(prefix)); + const dynamic = origin.routePrefix(Path.from(prefix)); void (async () => { for await (const request of dynamic.requested()) { const served = new BroadcastProducer(); @@ -461,9 +458,8 @@ test("a listing over a session carries each track's info, end to end", async () connect({ url, transport: pair.client }), accept({ transport: pair.server, url, publish: origin.consume() }), ]); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("a", { timescale: Timescale.MILLI, maxAge: Milli(3000), @@ -497,10 +493,13 @@ test("an instance-pinned front lists its serving route's tracks", async () => { connect({ url, transport: pair.client, consume: clientOrigin }), accept({ transport: pair.server, url, publish: serverOrigin.consume() }), ]); - const broadcastPublication = serverOrigin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; + const broadcastRoute = serverOrigin.route(Path.from("room"), { + hidden: true, + instance: Instance.parse("01900000-0000-7000-8000-000000000001"), + }); + const broadcast = broadcastRoute.broadcast; broadcast.createTrack("a"); - broadcastPublication.announce({ instance: Instance.parse("01900000-0000-7000-8000-000000000001") }); + broadcastRoute.announce(); const reader = clientOrigin.consume(); const announced = reader.routes(); @@ -525,7 +524,7 @@ test("an instance-pinned front lists its serving route's tracks", async () => { test("a front pinned to a named instance served through a covering prefix route is NOT_FOUND", async () => { const origin = new OriginProducer(); - const dynamic = origin.requestsRoute(Path.from("room"), { instance: Instance.parse("named") }); + const dynamic = origin.routePrefix(Path.from("room"), { instance: Instance.parse("named") }); void (async () => { for await (const request of dynamic.requested()) { const served = new BroadcastProducer(); @@ -551,9 +550,8 @@ test("lite-06 cannot list over a session", async () => { connect({ url, transport: pair.client }), accept({ transport: pair.server, url, publish: origin.consume() }), ]); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("room")); + const broadcast = broadcastRoute.broadcast; const tracks = wireOf(client).consume(Path.from("room")).tracks(); expect(await next(tracks)).toMatch(/requires moq-lite-07/); broadcast.close(); diff --git a/js/net/src/lite/widened_max_age.test.ts b/js/net/src/lite/widened_max_age.test.ts index 6bc779b4cb9..9ef760cfb96 100644 --- a/js/net/src/lite/widened_max_age.test.ts +++ b/js/net/src/lite/widened_max_age.test.ts @@ -28,8 +28,7 @@ async function received(reader: TrackSubscriber, count: number): Promise { const pair = createMockTransportPair(ALPN_07_WIP); const origin = new OriginProducer(); - const publication = origin.createBroadcast(Path.from("room")); - publication.announce(); + const publication = origin.route(Path.from("room")); const broadcast = publication.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); // One group per second, so a budget picks how far back a reader reaches. diff --git a/js/net/src/order.test.ts b/js/net/src/order.test.ts index f78d2df0efa..4ddba1863dc 100644 --- a/js/net/src/order.test.ts +++ b/js/net/src/order.test.ts @@ -139,9 +139,8 @@ async function backlog(protocol: string, order: Order, update?: Order) { const origin = new OriginProducer(); const { client, server, transport } = await session(protocol, origin); - const broadcastPublication = origin.createBroadcast(Path.from("test")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("test")); + const broadcast = broadcastRoute.broadcast; const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const groups = [0, 1, 2].map(() => writeGroup(video)); @@ -193,9 +192,8 @@ test.each(["ascending", "descending"] as const)("ietf serves GROUP_ORDER %s", as const origin = new OriginProducer(); const { client, server, transport } = await session(Ietf.ALPN.DRAFT_18, origin); - const broadcastPublication = origin.createBroadcast(Path.from("test")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("test")); + const broadcast = broadcastRoute.broadcast; const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const remote = wireOf(client).consume(Path.from("test")); @@ -261,9 +259,8 @@ test("ietf keeps a closing group stream ranked until it settles", async () => { const { client, server, transport } = await session(Ietf.ALPN.DRAFT_18, origin); const fins = holdFins(transport); - const broadcastPublication = origin.createBroadcast(Path.from("test")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("test")); + const broadcast = broadcastRoute.broadcast; const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const remote = wireOf(client).consume(Path.from("test")); @@ -302,9 +299,8 @@ test("a shared track aggregates descending and serves each subscriber in its own session(Lite.ALPN_07_WIP, origin), ]); - const broadcastPublication = origin.createBroadcast(Path.from("test")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("test")); + const broadcast = broadcastRoute.broadcast; const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const ascendingRemote = wireOf(ascending.client).consume(Path.from("test")); diff --git a/js/net/src/origin-demand.test.ts b/js/net/src/origin-demand.test.ts index 018a10d7679..a3511747e5d 100644 --- a/js/net/src/origin-demand.test.ts +++ b/js/net/src/origin-demand.test.ts @@ -27,7 +27,7 @@ test.each(["lite", "ietf", "fetch", "track"] as const)( async (kind) => { const pair = createMockTransportPair(); const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const publisher = kind === "ietf" ? new IetfPublisher({ @@ -106,7 +106,7 @@ test.each(["lite", "ietf", "fetch", "track"] as const)( test("last cancellation finishes the internal wait and discards a late consumer", async () => { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const requests = dynamic.requested(); const hold = new AbortController(); const wait = wireOf(origin.consume()).demand(path, undefined, hold.signal); @@ -134,7 +134,7 @@ test("last cancellation finishes the internal wait and discards a late consumer" expect(source.closed.peek()).toBeUndefined(); fresh.serve(source); await settle(); - expect(next.active.peek()?.instance).toBe(dynamic.route.instance); + expect(next.active.peek()?.instance).toBe(dynamic.instance); next.close(); keeper.close(); source.close(); @@ -149,7 +149,7 @@ test.each([true, false])( "shared local/remote demand is withdrawn whichever leaves last (local first: %s)", async (localFirst) => { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const requests = dynamic.requested(); const hold = new AbortController(); const wait = wireOf(origin.consume()) @@ -193,13 +193,13 @@ test.each([ ] as const)("cancelling one waiter preserves a second %s requester across %i routes", async (other, routes) => { const origin = new Producer(); const prefix = Path.from("room"); - const dynamics = Array.from({ length: routes }, (_, i) => origin.requestsRoute(prefix, { cost: BigInt(i) })); + const dynamics = Array.from({ length: routes }, (_, i) => origin.routePrefix(prefix, { cost: BigInt(i) })); const hold = new AbortController(); const wire = wireOf(origin.consume()); const first = wire.demand(path, undefined, hold.signal).catch(() => undefined); // With competing routes, re-price the cancelled waiter's route so the survivor pends on another. const cancelled = dynamics[0]; - if (routes > 1) cancelled.updateRoute({ ...cancelled.route, cost: BigInt(routes) }); + if (routes > 1) cancelled.setCost(BigInt(routes)); const requests = dynamics[routes > 1 ? 1 : 0].requested(); const second = other === "peer" ? wire.demand(path) : undefined; const local = other === "local" ? origin.request(path) : undefined; @@ -212,7 +212,7 @@ test.each([ request.serve(source); await settle(); if (other === "peer") expect((await second)?.closed).toBe(source.closed); - else expect(local?.active.peek()?.instance).toBe(dynamics[routes > 1 ? 1 : 0].route.instance); + else expect(local?.active.peek()?.instance).toBe(dynamics[routes > 1 ? 1 : 0].instance); } finally { local?.close(); origin.close(); @@ -223,7 +223,7 @@ test.each([ test("an already cancelled signal never enqueues or subscribes to abort", async () => { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const requests = dynamic.requested(); const hold = new AbortController(); hold.abort(); @@ -245,7 +245,7 @@ test.each(["accept", "reject", "cancel"] as const)( "%s releases the abort listener without closing a shared producer", async (action) => { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const requests = dynamic.requested(); const source = new Broadcast(); const keeper = source.consume(); @@ -281,12 +281,12 @@ test.each(["accept", "reject", "cancel"] as const)( test("a pending local request changing routes withdraws the old route's work", async () => { const origin = new Producer(); - const first = origin.requestsRoute(Path.from("room"), { cost: 5n }); + const first = origin.routePrefix(Path.from("room"), { cost: 5n }); const a = first.requested(); const local = origin.request(path); const old = (await a.next()).value; if (!old) throw new Error("expected a pending request"); - const second = origin.requestsRoute(Path.from("room"), { cost: 1n }); + const second = origin.routePrefix(Path.from("room"), { cost: 1n }); const b = second.requested(); const fresh = (await b.next()).value; if (!fresh) throw new Error("expected a pending request"); @@ -299,7 +299,7 @@ test("a pending local request changing routes withdraws the old route's work", a expect(close).toHaveBeenCalledTimes(1); fresh.serve(source); await settle(); - expect(local.active.peek()?.instance).toBe(second.route.instance); + expect(local.active.peek()?.instance).toBe(second.instance); } finally { close.mockRestore(); local.close(); @@ -314,7 +314,7 @@ test("a pending local request changing routes withdraws the old route's work", a test("cancelling an old instance waiter does not decrement a new instance's demand", async () => { const origin = new Producer(); const instance = Instance.random(); - const dynamic = origin.requestsRoute(Path.from("room"), { instance }); + const dynamic = origin.routePrefix(Path.from("room"), { instance }); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const hold = new AbortController(); @@ -322,7 +322,7 @@ test("cancelling an old instance waiter does not decrement a new instance's dema const old = (await requests.next()).value; if (!old) throw new Error("expected old request"); const next = Instance.random(); - dynamic.updateRoute({ instance: next }); + wireOf(dynamic).update({ instance: next }); const after = wire.demand(path, next); hold.abort(); await before; @@ -346,8 +346,8 @@ test.each(["answer", "release"] as const)( const origin = new Producer(); const instance = Instance.random(); const prefix = Path.from("room"); - const a = origin.requestsRoute(prefix, { instance, cost: 1n }); - const b = origin.requestsRoute(prefix, { instance, cost: 5n }); + const a = origin.routePrefix(prefix, { instance, cost: 1n }); + const b = origin.routePrefix(prefix, { instance, cost: 5n }); const ar = a.requested(); const br = b.requested(); const held = origin.request(path); @@ -355,7 +355,7 @@ test.each(["answer", "release"] as const)( (await ar.next()).value.serve(source); await settle(); // Another instance wins new requests. The old handle stays on its own instance. - const c = origin.requestsRoute(prefix, { instance: Instance.random(), cost: 0n }); + const c = origin.routePrefix(prefix, { instance: Instance.random(), cost: 0n }); a.close(); await settle(); const pending = (await br.next()).value; @@ -407,8 +407,8 @@ test.each([0, 1])( // Each instance undercuts the last, so it wins the path for the request made now. const instance = Instance.parse(`instance-${i + 1}`); const cost = BigInt(4 - 2 * i); - const primary = origin.requestsRoute(prefix, { instance, cost }); - const standby = origin.requestsRoute(prefix, { instance, cost: cost + 1n }); + const primary = origin.routePrefix(prefix, { instance, cost }); + const standby = origin.routePrefix(prefix, { instance, cost: cost + 1n }); const ar = primary.requested(); const br = standby.requested(); const held = origin.request(path); @@ -418,7 +418,7 @@ test.each([0, 1])( await settle(); entries.push({ primary, ar, br, held }); } - origin.requestsRoute(prefix, { instance: Instance.parse("instance-3"), cost: 0n }); + origin.routePrefix(prefix, { instance: Instance.parse("instance-3"), cost: 0n }); const pending = []; for (const entry of entries) { entry.primary.close(); @@ -459,7 +459,7 @@ test.each([0, 1])( test("a normal FETCH request FIN keeps unanswered origin demand alive", async () => { const pair = createMockTransportPair(); const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const requests = dynamic.requested(); const publisher = new LitePublisher(pair.server, LiteVersion.DRAFT_06, randomHop(), origin.consume()); let input!: ReadableStreamDefaultController; @@ -500,7 +500,7 @@ test.each(["accept", "reject"] as const)( "cancellation racing %s releases only the cancelled waiter", async (answer) => { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const hold = new AbortController(); @@ -529,7 +529,7 @@ test.each(["accept", "reject"] as const)( test.each([true, false])("last waiter cancellation and accept in one turn (cancel first: %s)", async (cancelFirst) => { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const hold = new AbortController(); @@ -570,7 +570,7 @@ test.each([true, false])("last waiter cancellation and accept in one turn (cance test.each([true, false])("local demand survives same-turn cancellation only when rejoined: %s", async (rejoin) => { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const requests = dynamic.requested(); const local = origin.request(path); const hold = new AbortController(); @@ -592,7 +592,7 @@ test.each([true, false])("local demand survives same-turn cancellation only when expect(close).toHaveBeenCalledTimes(rejoin ? 0 : 1); if (replacement) { await settle(); - expect(replacement.active.peek()?.instance).toBe(dynamic.route.instance); + expect(replacement.active.peek()?.instance).toBe(dynamic.instance); } else { const fresh = origin.request(path); const next = (await requests.next()).value; @@ -600,7 +600,7 @@ test.each([true, false])("local demand survives same-turn cancellation only when if (!next) throw new Error("expected fresh request"); next.serve(source); await settle(); - expect(fresh.active.peek()?.instance).toBe(dynamic.route.instance); + expect(fresh.active.peek()?.instance).toBe(dynamic.instance); fresh.close(); } } finally { @@ -616,7 +616,7 @@ test.each([true, false])("local demand survives same-turn cancellation only when test("queued cancellation preserves order, replacement identity, and empty-queue wakeup", async () => { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const holds = Array.from({ length: 4 }, () => new AbortController()); @@ -642,7 +642,7 @@ test("queued cancellation preserves order, replacement identity, and empty-queue test("reset clears queued work while a handler is suspended and admits the new instance", async () => { const origin = new Producer(); const instance = Instance.random(); - const dynamic = origin.requestsRoute(Path.from("room"), { instance }); + const dynamic = origin.routePrefix(Path.from("room"), { instance }); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const waits = [path, Path.from("room/obsolete")].map((name) => wire.demand(name, instance).catch(() => {})); @@ -650,7 +650,7 @@ test("reset clears queued work while a handler is suspended and admits the new i const old = (await requests.next()).value; expect(old?.path).toBe(path); const next = Instance.random(); - dynamic.updateRoute({ instance: next }); + wireOf(dynamic).update({ instance: next }); waits.push(wire.demand(path, next).catch(() => {})); const fresh = (await requests.next()).value; expect(fresh?.path).toBe(path); @@ -666,7 +666,7 @@ test("reset clears queued work while a handler is suspended and admits the new i test("concurrent handlers consume queued requests once across empty batches", async () => { const origin = new Producer(); - const dynamic = origin.requestsRoute(Path.from("room")); + const dynamic = origin.routePrefix(Path.from("room")); const handlers = [dynamic.requested(), dynamic.requested()]; const wire = wireOf(origin.consume()); const waits: Promise[] = []; diff --git a/js/net/src/origin-request.test.ts b/js/net/src/origin-request.test.ts index 38074e798ee..aabf3d94108 100644 --- a/js/net/src/origin-request.test.ts +++ b/js/net/src/origin-request.test.ts @@ -1,9 +1,9 @@ import { expect, test } from "bun:test"; import { Producer as BroadcastProducer } from "./broadcast"; import { StreamCode, StreamError } from "./error"; -import { Route } from "./hop"; +import { RouteInfo } from "./hop"; import * as Instance from "./instance.ts"; -import { type Following, Producer, type Publication, type Requesting } from "./origin"; +import { type Following, Producer, type Requesting } from "./origin"; import * as Path from "./path"; import { wireOf } from "./wire"; @@ -12,25 +12,22 @@ const settle = () => new Promise((resolve) => setImmediate(resolve)); test("a follower moves through restart, end and a later start", async () => { const origin = new Producer(); const path = Path.from("room/audio"); - const firstPublication = origin.createBroadcast(path); - const first = firstPublication.broadcast; - firstPublication.announce(); + const firstRoute = origin.route(path); + const first = firstRoute.broadcast; const request: Following = origin.follow(path); - expect(request.active.peek()?.instance).toBe(firstPublication.route?.instance); - const secondPublication = origin.createBroadcast(path); - const second = secondPublication.broadcast; - secondPublication.announce(); + expect(request.active.peek()?.instance).toBe(firstRoute.instance); + const secondRoute = origin.route(path); + const second = secondRoute.broadcast; await settle(); - expect(request.active.peek()?.instance).toBe(secondPublication.route?.instance); + expect(request.active.peek()?.instance).toBe(secondRoute.instance); second.close(); await settle(); expect(request.active.peek()).toBeUndefined(); expect(request.closed.peek()).toBeUndefined(); - const thirdPublication = origin.createBroadcast(path); - const third = thirdPublication.broadcast; - thirdPublication.announce(); + const thirdRoute = origin.route(path); + const third = thirdRoute.broadcast; await settle(); - expect(request.active.peek()?.instance).toBe(thirdPublication.route?.instance); + expect(request.active.peek()?.instance).toBe(thirdRoute.instance); request.close(); third.close(); first.close(); @@ -41,15 +38,13 @@ test("an instance-pinned follower refuses another instance", async () => { const origin = new Producer(); const path = Path.from("room/audio"); const instance = Instance.random(); - const firstPublication = origin.createBroadcast(path); - const first = firstPublication.broadcast; - firstPublication.announce({ instance }); + const firstRoute = origin.route(path, { instance }); + const first = firstRoute.broadcast; const request = origin.follow(path, { instance }); - const secondPublication = origin.createBroadcast(path); - const second = secondPublication.broadcast; - secondPublication.announce({ instance: Instance.random() }); + const secondRoute = origin.route(path, { instance: Instance.random() }); + const second = secondRoute.broadcast; await settle(); - expect(request.active.peek()?.instance).not.toBe(secondPublication.route?.instance); + expect(request.active.peek()?.instance).not.toBe(secondRoute.instance); request.close(); first.close(); second.close(); @@ -59,14 +54,14 @@ test("an instance-pinned follower refuses another instance", async () => { test("a follower changes its handle on an in-place instance restart", async () => { const origin = new Producer(); const path = Path.from("room/audio"); - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; const before = Instance.random(); - broadcastPublication.announce({ instance: before }); + const broadcastRoute = origin.route(path, { instance: before }); + const broadcast = broadcastRoute.broadcast; const request = origin.follow(path); const old = request.active.peek(); const after = Instance.random(); - broadcastPublication.announce({ instance: after }); + // A session's in-place restart: the route's instance changes under it. + wireOf(broadcastRoute).update({ instance: after }); await settle(); expect(request.active.peek()?.instance).toBe(after); expect(request.active.peek()).not.toBe(old); @@ -80,9 +75,8 @@ test("a closed follower never acquires another publisher", async () => { const path = Path.from("room/audio"); const request = origin.follow(path); request.close(); - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; await settle(); expect(request.active.peek()).toBeUndefined(); expect(request.closed.peek()).toBeNull(); @@ -108,11 +102,10 @@ test("unrelated routes never notify followers", async () => { await settle(); let changes = 0; const stops = requests.map((request) => request.active.subscribe(() => changes++)); - const otherPublication = origin.createBroadcast(Path.from("unrelated")); - const other = otherPublication.broadcast; - otherPublication.announce(); + const otherRoute = origin.route(Path.from("unrelated")); + const other = otherRoute.broadcast; await settle(); - otherPublication.announce({ cost: 5n }); + otherRoute.setCost(5n); await settle(); other.close(); await settle(); @@ -167,29 +160,27 @@ test("followers track the serving prefix, ignoring descendants and re-prices", a const origin = new Producer(); const source = new BroadcastProducer(); const keeper = source.consume(); - const prefix = origin.requestsRoute(Path.from("pool")); + const prefix = origin.routePrefix(Path.from("pool")); const serving = (async () => { for await (const request of prefix.requested()) request.serve(source.consume()); })(); const request = origin.follow(Path.from("pool/job")); await settle(); - expect(request.active.peek()?.instance).toBe(prefix.route.instance); - const belowPublication = origin.createBroadcast(Path.from("pool/job/thumb")); - const below = belowPublication.broadcast; - belowPublication.announce(); + expect(request.active.peek()?.instance).toBe(prefix.instance); + const belowRoute = origin.route(Path.from("pool/job/thumb")); + const below = belowRoute.broadcast; await settle(); - expect(request.active.peek()?.instance).toBe(prefix.route.instance); - const exactPublication = origin.createBroadcast(Path.from("pool/job")); - const exact = exactPublication.broadcast; - exactPublication.announce(); + expect(request.active.peek()?.instance).toBe(prefix.instance); + const exactRoute = origin.route(Path.from("pool/job")); + const exact = exactRoute.broadcast; await settle(); - expect(request.active.peek()?.instance).toBe(exactPublication.route?.instance); - prefix.updateRoute({ cost: 5n }); + expect(request.active.peek()?.instance).toBe(exactRoute.instance); + prefix.setCost(5n); await settle(); - expect(request.active.peek()?.instance).toBe(exactPublication.route?.instance); + expect(request.active.peek()?.instance).toBe(exactRoute.instance); exact.close(); await settle(); - expect(request.active.peek()?.instance).toBe(prefix.route.instance); + expect(request.active.peek()?.instance).toBe(prefix.instance); prefix.close(); await settle(); expect(request.active.peek()).toBeUndefined(); @@ -205,12 +196,11 @@ test("followers track the serving prefix, ignoring descendants and re-prices", a test("a follower ignores a covering route whose scope excludes its path", async () => { const origin = new Producer(); const scoped = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/*/chat")])); - const prefix = scoped.requestsRoute(Path.from("room/alice")); - const exactPublication = origin.createBroadcast(Path.from("room/alice")); - const exact = exactPublication.broadcast; - exactPublication.announce({ cost: 5n }); + const prefix = scoped.routePrefix(Path.from("room/alice")); + const exactRoute = origin.route(Path.from("room/alice"), { cost: 5n }); + const exact = exactRoute.broadcast; const request = origin.follow(Path.from("room/alice")); - expect(request.active.peek()?.instance).toBe(exactPublication.route?.instance); + expect(request.active.peek()?.instance).toBe(exactRoute.instance); exact.close(); await settle(); expect(request.active.peek()).toBeUndefined(); @@ -223,7 +213,7 @@ test("a follower tracks a route replaced by an identical one", async () => { const origin = new Producer(); const path = Path.from("room"); const serve = (source: BroadcastProducer) => { - const route = origin.requestsRoute(path); + const route = origin.routePrefix(path); void (async () => { for await (const request of route.requested()) request.serve(source.consume()); })(); @@ -233,7 +223,7 @@ test("a follower tracks a route replaced by an identical one", async () => { const first = serve(firstSource); const request = origin.follow(path); await settle(); - expect(request.active.peek()?.instance).toBe(first.route.instance); + expect(request.active.peek()?.instance).toBe(first.instance); // Same (default) route metadata: only the instance each claim minted differs. const secondSource = new BroadcastProducer(); @@ -241,7 +231,7 @@ test("a follower tracks a route replaced by an identical one", async () => { await settle(); first.close(); await settle(); - expect(request.active.peek()?.instance).toBe(second.route.instance); + expect(request.active.peek()?.instance).toBe(second.instance); request.close(); second.close(); @@ -254,7 +244,7 @@ test("an origin closing settles a follower a served route resolved", async () => const origin = new Producer(); const path = Path.from("room"); const source = new BroadcastProducer(); - const route = origin.requestsRoute(path); + const route = origin.routePrefix(path); void (async () => { for await (const request of route.requested()) request.serve(source.consume()); })(); @@ -273,14 +263,14 @@ test("an origin closing settles a follower a served route resolved", async () => test("a follower keeps a refusal that lands with a re-price", async () => { const origin = new Producer(); const path = Path.from("room"); - const route = origin.requestsRoute(path); + const route = origin.routePrefix(path); const requested = route.requested(); const request = origin.follow(path); const pending = (await requested.next()).value; if (!pending) throw new Error("expected a request"); // Both land in one turn: the watch notification must not retry the refused request. - route.updateRoute({ cost: 5n }); + route.setCost(5n); const denied = new Error("denied"); pending.reject(denied); await settle(); @@ -304,7 +294,7 @@ for (const received of [false, true]) { const events: string[] = []; const stop = wireOf(origin).interests((prefix, wanted) => events.push(`${prefix} ${wanted}`)); const source = new BroadcastProducer(); - const route = received ? wireOf(origin).receive(path, Route.default) : origin.requestsRoute(path); + const route = received ? wireOf(origin).receive(path, RouteInfo.default) : origin.routePrefix(path); void (async () => { for await (const request of route.requested()) request.serve(source.consume()); })(); @@ -325,55 +315,85 @@ for (const received of [false, true]) { }); } -test("a claim answer is hidden until published under its own instance", async () => { +test("a hidden job route is hidden until announced under its own instance", async () => { const origin = new Producer(); const path = Path.from("room/alice"); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); const requests = claim.requested(); const request = origin.request(path); const pending = (await requests.next()).value; if (!pending) throw new Error("expected a request"); - const prepared = pending.prepare(); - prepared.broadcast.createTrack("video"); + const job = pending.route({ hidden: true }); + job.broadcast.createTrack("video"); await settle(); expect(request.active.peek()).toBeUndefined(); - const published = prepared.publish(); + job.announce(); await settle(); - expect(published.route?.instance).toBeDefined(); - expect(request.active.peek()?.instance).toBe(published.route?.instance); + expect(request.active.peek()?.instance).toBe(job.instance); request.close(); - published.broadcast.close(); + job.close(); claim.close(); origin.close(); }); -test("a prepared answer cannot announce itself before publish", async () => { +test("a visible job route answers its waiting requesters at once", async () => { const origin = new Producer(); const path = Path.from("room/alice"); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); + const requests = claim.requested(); + const first = origin.request(path); + const pending = (await requests.next()).value; + if (!pending) throw new Error("expected a request"); + const shared = origin.request(path); + const job = pending.route(); + expect(job.announced).toBe(true); + expect(job.instance).not.toBe(claim.instance); + await settle(); + for (const request of [first, shared]) expect(request.active.peek()?.instance).toBe(job.instance); + // The request is answered: routing it again is refused. + expect(() => pending.route()).toThrow("request is closed"); + + // Ending the job withdraws only its path: the claim keeps answering later requests. + job.close(); + await settle(); + const later = origin.request(path); + const next = (await requests.next()).value; + if (!next) throw new Error("expected another request"); + const again = next.route({ instance: Instance.parse("stable"), epoch: 2n }); + await settle(); + expect(again.instance).toBe(Instance.parse("stable")); + expect(later.active.peek()?.instance).toBe(again.instance); + for (const request of [first, shared, later]) request.close(); + again.close(); + claim.close(); + origin.close(); +}); + +test("a hidden job route's broadcast cannot announce itself", async () => { + const origin = new Producer(); + const path = Path.from("room/alice"); + const claim = origin.routePrefix(Path.from("room")); const requests = claim.requested(); const request = origin.request(path); const pending = (await requests.next()).value; if (!pending) throw new Error("expected a request"); - const prepared = pending.prepare(); - expect(prepared.broadcast).not.toHaveProperty("announce"); - expect(prepared.broadcast).not.toHaveProperty("route"); + const job = pending.route({ hidden: true }); + expect(job.broadcast).not.toHaveProperty("announce"); + expect(job.broadcast).not.toHaveProperty("route"); await settle(); expect(request.active.peek()).toBeUndefined(); - const published = prepared.publish(); - const instance = published.route?.instance; - expect(instance).toBeDefined(); + job.announce(); await settle(); - expect(request.active.peek()?.instance).toBe(instance); + expect(request.active.peek()?.instance).toBe(job.instance); request.close(); - published.broadcast.close(); + job.close(); claim.close(); origin.close(); }); test("an application serves held content without an exact route", async () => { const origin = new Producer(); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); const requests = claim.requested(); const request = origin.request(Path.from("room/alice")); const pending = (await requests.next()).value; @@ -392,20 +412,20 @@ test("an application serves held content without an exact route", async () => { origin.close(); }); -for (const withdraw of ["unannounce", "replace"] as const) { - test(`a published answer is not cached after ${withdraw}`, async () => { +for (const withdraw of ["withdraw", "replace"] as const) { + test(`a job's route is not cached after ${withdraw}`, async () => { const origin = new Producer(); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); const requests = claim.requested(); const path = Path.from("room/alice"); const first = origin.request(path); const pending = (await requests.next()).value; if (!pending) throw new Error("expected a request"); - const publication = pending.prepare().publish(); + const job = pending.route(); await settle(); const held = first.active.peek()?.clone(); - if (withdraw === "unannounce") publication.unannounce(); - else origin.createBroadcast(path).broadcast.close(); + if (withdraw === "withdraw") job.withdraw(); + else origin.route(path, { hidden: true }).broadcast.close(); const next = origin.request(path); await settle(); expect(next.active.peek()).toBeUndefined(); @@ -415,41 +435,43 @@ for (const withdraw of ["unannounce", "replace"] as const) { held?.close(); next.close(); first.close(); - publication.broadcast.close(); + job.close(); claim.close(); origin.close(); }); } -test("closing a prepared answer refuses the request and closes its broadcast", async () => { +test("closing a hidden job route refuses the request and closes its broadcast", async () => { const origin = new Producer(); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); const requests = claim.requested(); const request = origin.request(Path.from("room/alice")); const pending = (await requests.next()).value; if (!pending) throw new Error("expected a request"); - const prepared = pending.prepare(); - prepared.close(); - prepared.close(); - prepared[Symbol.dispose](); + const job = pending.route({ hidden: true }); + job.close(); + job.close(); + job[Symbol.dispose](); await settle(); expect(request.closed.peek()).toBeInstanceOf(Error); - expect(prepared.broadcast.closed.peek()).toBeDefined(); + expect(job.broadcast.closed.peek()).toBeDefined(); claim.close(); origin.close(); }); -test("an answer prepared for an abandoned claim is never announced", async () => { +test("a job route for an abandoned claim is never announced", async () => { const origin = new Producer(); const path = Path.from("room/alice"); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); const requests = claim.requested(); const request = origin.request(path); const pending = (await requests.next()).value; if (!pending) throw new Error("expected a request"); - const prepared = pending.prepare(); + const job = pending.route({ hidden: true }); claim.close(); - expect(() => prepared.publish()).toThrow("request is closed"); + expect(() => job.announce()).toThrow("unroutable"); + expect(job.announced).toBe(false); + expect(job.broadcast.closed.peek()).toBeDefined(); const announced = origin.follow(path); await settle(); expect(announced.active.peek()).toBeUndefined(); @@ -459,31 +481,31 @@ test("an answer prepared for an abandoned claim is never announced", async () => }); for (const cleanup of ["close", "dispose", "broadcast"] as const) { - test(`prepared ${cleanup} releases shared requesters and admits a new request`, async () => { + test(`a hidden job route's ${cleanup} releases shared requesters and admits a new request`, async () => { const origin = new Producer(); const path = Path.from("room/alice"); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); const requests = claim.requested(); const first = origin.request(path); const pending = (await requests.next()).value; if (!pending) throw new Error("expected a request"); - const prepared = pending.prepare(); + const job = pending.route({ hidden: true }); const shared = origin.request(path); - if (cleanup === "close") prepared.close(); - else if (cleanup === "dispose") prepared[Symbol.dispose](); - else prepared.broadcast.close(); + if (cleanup === "close") job.close(); + else if (cleanup === "dispose") job[Symbol.dispose](); + else job.broadcast.close(); // Requested in the same turn, so the release cannot wait on a reactive notification. const later = origin.request(path); await settle(); - prepared.close(); - prepared[Symbol.dispose](); + job.close(); + job[Symbol.dispose](); for (const request of [first, shared]) { expect(request.closed.peek()).toBeInstanceOf(StreamError); expect((request.closed.peek() as StreamError).code).toBe(StreamCode.Unroutable); } expect(later.closed.peek()).toBeUndefined(); - expect(() => prepared.publish()).toThrow("prepared answer is closed"); + expect(() => job.announce()).toThrow("broadcast is closed"); const next = (await requests.next()).value; if (!next) throw new Error("expected another request"); expect(next).not.toBe(pending); @@ -495,14 +517,14 @@ for (const cleanup of ["close", "dispose", "broadcast"] as const) { }); } -test("a throwing handler disposes its prepared answer and leaves the claim answerable", async () => { +test("a throwing handler disposes its job route and leaves the claim answerable", async () => { const origin = new Producer(); const path = Path.from("room/alice"); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); const failed = (async () => { for await (const request of claim.requested()) { - using prepared = request.prepare(); - prepared.broadcast.createTrack("video"); + using job = request.route({ hidden: true }); + job.broadcast.createTrack("video"); throw new Error("handler failed"); } })(); @@ -515,8 +537,8 @@ test("a throwing handler disposes its prepared answer and leaves the claim answe const pending = (await requests.next()).value; if (!pending) throw new Error("expected another request"); { - using prepared = pending.prepare(); - prepared.close(); + using job = pending.route({ hidden: true }); + job.close(); } await settle(); expect((later.closed.peek() as StreamError).code).toBe(StreamCode.Unroutable); @@ -524,44 +546,40 @@ test("a throwing handler disposes its prepared answer and leaves the claim answe origin.close(); }); -test("using transfers a published answer without closing it on disposal", async () => { +test("announcing a job route again keeps it answering under one instance", async () => { const origin = new Producer(); const path = Path.from("room/alice"); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); const requests = claim.requested(); const request = origin.request(path); const pending = (await requests.next()).value; if (!pending) throw new Error("expected a request"); - let published: Publication; - { - using prepared = pending.prepare(); - prepared.broadcast.createTrack("data").writeFrame({ payload: new TextEncoder().encode("published") }); - published = prepared.publish(); - expect(() => prepared.publish()).toThrow("prepared answer is closed"); - prepared.close(); - } + const job = pending.route({ hidden: true }); + job.broadcast.createTrack("data").writeFrame({ payload: new TextEncoder().encode("published") }); + job.announce(); + job.announce(); await settle(); - expect(published.broadcast.closed.peek()).toBeUndefined(); - expect(request.active.peek()?.instance).toBe(published.route?.instance); + expect(job.broadcast.closed.peek()).toBeUndefined(); + expect(request.active.peek()?.instance).toBe(job.instance); const reader = request.active.peek()?.track("data").subscribe().ordered(); expect(await reader?.readString()).toBe("published"); reader?.close(); request.close(); - published.broadcast.close(); + job.close(); claim.close(); origin.close(); }); -for (const cleanup of ["close", "dispose", "broadcast", "publish"] as const) { - test(`an old prepared ${cleanup} cannot refuse the next request for its path`, async () => { +for (const cleanup of ["close", "dispose", "broadcast", "announce"] as const) { + test(`an old job route's ${cleanup} cannot refuse the next request for its path`, async () => { const origin = new Producer(); const path = Path.from("room/alice"); - const claim = origin.requests(Path.from("room")); + const claim = origin.routePrefix(Path.from("room")); const requests = claim.requested(); const first = origin.request(path); const pending = (await requests.next()).value; if (!pending) throw new Error("expected a request"); - const old = pending.prepare(); + const old = pending.route({ hidden: true }); first.close(); await settle(); const later = origin.request(path); @@ -570,34 +588,33 @@ for (const cleanup of ["close", "dispose", "broadcast", "publish"] as const) { if (cleanup === "close") old.close(); else if (cleanup === "dispose") old[Symbol.dispose](); else if (cleanup === "broadcast") old.broadcast.close(); - else expect(() => old.publish()).toThrow("request is closed"); + else expect(() => old.announce()).toThrow("unroutable"); await settle(); expect(later.closed.peek()).toBeUndefined(); - using prepared = next.prepare(); - prepared.broadcast.createTrack("data").writeFrame({ payload: new TextEncoder().encode(cleanup) }); - const published = prepared.publish(); + using job = next.route({ hidden: true }); + job.broadcast.createTrack("data").writeFrame({ payload: new TextEncoder().encode(cleanup) }); + job.announce(); await settle(); - expect(later.active.peek()?.instance).toBe(published.route?.instance); + expect(later.active.peek()?.instance).toBe(job.instance); const reader = later.active.peek()?.track("data").subscribe().ordered(); expect(await reader?.readString()).toBe(cleanup); reader?.close(); old.close(); later.close(); - published.broadcast.close(); claim.close(); origin.close(); }); } -test("a forwarded request cannot be prepared by setting a publisher property", async () => { +test("a forwarded request cannot be routed by setting a publisher property", async () => { const origin = new Producer(); - const route = origin.requestsRoute(Path.from("room")); + const route = wireOf(origin).receive(Path.from("room")); const requests = route.requested(); const request = origin.request(Path.from("room/alice")); const pending = (await requests.next()).value; if (!pending) throw new Error("expected a request"); Object.assign(pending, { publisher: origin }); - expect(() => pending.prepare()).toThrow("forwarded requests cannot be prepared"); + expect(() => pending.route()).toThrow("unroutable"); pending.reject(new Error("refused")); request.close(); route.close(); @@ -611,7 +628,7 @@ test("an instance-pinned follower resumes when its instance returns after a gap" const source = new BroadcastProducer(); const keeper = source.consume(); const serve = (instance: Instance.Valid, broadcast: BroadcastProducer) => { - const route = origin.requestsRoute(path, { instance: instance }); + const route = origin.routePrefix(path, { instance: instance }); void (async () => { for await (const request of route.requested()) request.serve(broadcast.consume()); })(); @@ -681,10 +698,9 @@ test("a follower keeps its scoped discovery across instances until closed", asyn synced?.(); await settle(); expect(follower.closed.peek()).toBeUndefined(); - const publication = origin.createBroadcast(path); - publication.announce(); + const publication = origin.route(path); await settle(); - expect(follower.active.peek()?.instance).toBe(publication.route?.instance); + expect(follower.active.peek()?.instance).toBe(publication.instance); publication.broadcast.close(); await settle(); // The instance ending keeps the follower and its discovery open for the next one. @@ -763,7 +779,7 @@ test("a pending request waits for a session before concluding absence", async () test("a follower retains a selected handler's explicit unroutable refusal", async () => { const origin = new Producer(); const path = Path.from("room/audio"); - const route = origin.requestsRoute(path); + const route = origin.routePrefix(path); const pending = route.requested(); const requested = origin.follow(path); const request = (await pending.next()).value; @@ -780,25 +796,24 @@ test("a follower retains a selected handler's explicit unroutable refusal", asyn test("a pending request retries a route gap and never retargets after resolving", async () => { const origin = new Producer(); const path = Path.from("room/audio"); - const first = origin.requestsRoute(path); + const first = origin.routePrefix(path); const requested = origin.request(path); const before = await first.requested().next(); expect(before.value).toBeDefined(); first.close(); await settle(); expect(requested.closed.peek()).toBeUndefined(); - const second = origin.requestsRoute(path); + const second = origin.routePrefix(path); const pending = (await second.requested().next()).value; if (!pending) throw new Error("replacement route was not requested"); const source = new BroadcastProducer(); const keeper = source.consume(); pending.serve(source.consume()); await settle(); - expect(requested.active.peek()?.instance).toBe(second.route.instance); - const replacement = origin.createBroadcast(path); - replacement.announce(); + expect(requested.active.peek()?.instance).toBe(second.instance); + const replacement = origin.route(path); await settle(); - expect(requested.active.peek()?.instance).toBe(second.route.instance); + expect(requested.active.peek()?.instance).toBe(second.instance); second.close(); await settle(); expect(requested.closed.peek()).toBeInstanceOf(StreamError); @@ -834,8 +849,8 @@ test.each(["request", "follow"] as const)("a %s pinned to a losing instance reso const origin = new Producer(); const path = Path.from("room/audio"); const pinned = Instance.random(); - const losing = origin.requestsRoute(path, { instance: pinned, cost: 9n }); - const winning = origin.requestsRoute(path, { instance: Instance.random(), cost: 1n }); + const losing = origin.routePrefix(path, { instance: pinned, cost: 9n }); + const winning = origin.routePrefix(path, { instance: Instance.random(), cost: 1n }); const asked = losing.requested(); const requested = origin[method](path, { instance: pinned }); const pending = (await asked.next()).value; @@ -855,12 +870,12 @@ test.each(["request", "follow"] as const)("a %s pinned to a losing instance reso const other = new BroadcastProducer(); answer.serve(other.consume()); await settle(); - expect(plain.active.peek()?.instance).toBe(winning.route.instance); + expect(plain.active.peek()?.instance).toBe(winning.instance); requested.close(); again.close(); await settle(); - expect(plain.active.peek()?.instance).toBe(winning.route.instance); + expect(plain.active.peek()?.instance).toBe(winning.instance); plain.close(); source.close(); other.close(); @@ -873,10 +888,9 @@ test("a peer's pin is served by a local broadcast that loses the path", async () const origin = new Producer(); const wire = wireOf(origin.consume()); const path = Path.from("room/audio"); - const publication = origin.createBroadcast(path); const pinned = Instance.random(); - publication.announce({ instance: pinned, cost: 9n }); - const winning = origin.requestsRoute(path, { instance: Instance.random(), cost: 1n }); + const publication = origin.route(path, { instance: pinned, cost: 9n }); + const winning = origin.routePrefix(path, { instance: Instance.random(), cost: 1n }); expect(wire.local(path)).toBeUndefined(); expect(wire.local(path, pinned)).toBeDefined(); expect(await wire.demand(path, pinned)).toBeDefined(); diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 36ad412a0c5..8c6ad7afda3 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -4,7 +4,7 @@ import { getter, Once, race, Signal } from "@moq/signals"; import { announcedView } from "./announced.test-util"; import { type Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "./broadcast.ts"; import { StreamCode, StreamError } from "./error.ts"; -import { HopSchema, Route } from "./hop.ts"; +import { type Cost, HopSchema, RouteInfo } from "./hop.ts"; import * as Instance from "./instance.ts"; import { chainHash, presented, spreadHash } from "./internal.ts"; import { SessionBroadcast, textFrame } from "./mock.ts"; @@ -16,9 +16,8 @@ import { Timescale } from "./time.ts"; import { overrideBroadcastWire, wireOf } from "./wire.ts"; function publish(origin: Producer, path: Path.Valid) { - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; return broadcast; } @@ -28,7 +27,12 @@ const PEER = HopSchema.parse(10n); const INSTANCE = Instance.parse("01900000-0000-7000-8000-000000000001"); /** Land a received prefix, served from `consume`, the way a session does. */ -function serve(origin: Producer, prefix: Path.Valid, consume: () => BroadcastConsumer, route: Route = Route.default) { +function serve( + origin: Producer, + prefix: Path.Valid, + consume: () => BroadcastConsumer, + route: RouteInfo = RouteInfo.default, +) { const handle = wireOf(origin).receive(prefix, route); void (async () => { try { @@ -120,35 +124,35 @@ test("a borrowed table exposes dynamic serving and a live scoped broadcast map", const table: Table = origin; const scope = Path.Pattern.parse("room/**"); const live = await announcedView(origin, scope); - const changes: ReadonlyMap[] = []; + const changes: ReadonlyMap[] = []; const stop = live.subscribe((value) => changes.push(value)); await new Promise((resolve) => setImmediate(resolve)); expect(live.peek().size).toBe(0); const other = publish(origin, Path.from("other")); const localPath = Path.from("room/alice"); - const localPublication = table.createBroadcast(localPath); - const local = localPublication.broadcast; + const localRoute = table.route(localPath, { hidden: true, instance: INSTANCE, cost: 4n }); + const local = localRoute.broadcast; await new Promise((resolve) => setImmediate(resolve)); expect(live.peek().has(localPath)).toBe(false); await new Promise((resolve) => setImmediate(resolve)); expect(live.peek().has(Path.from("other"))).toBe(false); - localPublication.announce({ instance: INSTANCE, cost: 4n }); + localRoute.announce(); await settle(); await new Promise((resolve) => setImmediate(resolve)); - expect(live.peek().get(localPath)).toEqual(Route.normalize({ instance: INSTANCE, cost: 4n })); + expect(live.peek().get(localPath)).toEqual(RouteInfo.normalize({ instance: INSTANCE, cost: 4n })); await new Promise((resolve) => setImmediate(resolve)); expect(changes.some((value) => value.get(localPath)?.cost === 4n)).toBe(true); const prefix = Path.from("room"); - const dynamic = table.requestsRoute(prefix, { cost: 2n }); + const dynamic = table.routePrefix(prefix, { cost: 2n }); await new Promise((resolve) => setImmediate(resolve)); - expect(live.peek().get(prefix)).toEqual(Route.normalize({ ...dynamic.route, cost: 2n })); - dynamic.updateRoute({ cost: 3n }); + expect(live.peek().get(prefix)).toEqual(RouteInfo.normalize({ ...wireOf(dynamic).info, cost: 2n })); + dynamic.setCost(3n); await settle(); await new Promise((resolve) => setImmediate(resolve)); - expect(live.peek().get(prefix)).toEqual(Route.normalize({ ...dynamic.route, cost: 3n })); + expect(live.peek().get(prefix)).toEqual(RouteInfo.normalize({ ...wireOf(dynamic).info, cost: 3n })); dynamic.close(); local.close(); @@ -167,26 +171,26 @@ test("an announced local path competes with a received route on cost", async () const remote = wireOf(origin).receive(path, { instance: INSTANCE, hops: [PEER], cost: 5n }); const live = await announcedView(consumer); await new Promise((resolve) => setImmediate(resolve)); - expect(live.peek().get(path)).toEqual(Route.normalize({ instance: INSTANCE, hops: [PEER], cost: 5n })); + expect(live.peek().get(path)).toEqual(RouteInfo.normalize({ instance: INSTANCE, hops: [PEER], cost: 5n })); // Unannounced, it competes for nothing. - const localPublication = origin.createBroadcast(path); - const local = localPublication.broadcast; + const localRoute = origin.route(path, { hidden: true, instance: INSTANCE, cost: 9n }); + const local = localRoute.broadcast; await new Promise((resolve) => setImmediate(resolve)); - expect(live.peek().get(path)).toEqual(Route.normalize({ instance: INSTANCE, hops: [PEER], cost: 5n })); + expect(live.peek().get(path)).toEqual(RouteInfo.normalize({ instance: INSTANCE, hops: [PEER], cost: 5n })); // Cheaper wins; a tie falls to the local broadcast. - localPublication.announce({ instance: INSTANCE, cost: 9n }); + localRoute.announce(); await new Promise((resolve) => setImmediate(resolve)); - expect(live.peek().get(path)).toEqual(Route.normalize({ instance: INSTANCE, hops: [PEER], cost: 5n })); - localPublication.announce({ instance: INSTANCE, cost: 5n }); + expect(live.peek().get(path)).toEqual(RouteInfo.normalize({ instance: INSTANCE, hops: [PEER], cost: 5n })); + localRoute.setCost(5n); await new Promise((resolve) => setImmediate(resolve)); - expect(live.peek().get(path)).toEqual(Route.normalize({ instance: INSTANCE, cost: 5n })); + expect(live.peek().get(path)).toEqual(RouteInfo.normalize({ instance: INSTANCE, cost: 5n })); local.close(); await settle(); await new Promise((resolve) => setImmediate(resolve)); - expect(live.peek().get(path)).toEqual(Route.normalize({ instance: INSTANCE, hops: [PEER], cost: 5n })); + expect(live.peek().get(path)).toEqual(RouteInfo.normalize({ instance: INSTANCE, hops: [PEER], cost: 5n })); remote.close(); await settle(); @@ -207,7 +211,7 @@ test("a scoped route remains visible when an exact local path is outside the sco await new Promise((resolve) => setImmediate(resolve)); - expect((await announcedView(origin)).peek().get(path)).toMatchObject(Route.default); + expect((await announcedView(origin)).peek().get(path)).toMatchObject(RouteInfo.default); await new Promise((resolve) => setImmediate(resolve)); expect(live.peek().get(path)).toMatchObject({ cost: 5n }); @@ -309,7 +313,7 @@ test("a superseded broadcast closes, and its subscribers keep reading", async () const consumer = origin.consume(); const path = Path.from("room"); - const publication = origin.createBroadcast(path); + const publication = origin.route(path, { hidden: true }); const first = publication.broadcast; const track = first.createTrack("video", { timescale: Timescale.MILLI }); publication.announce(); @@ -317,13 +321,12 @@ test("a superseded broadcast closes, and its subscribers keep reading", async () const subscriber = mine?.track("video").subscribe(); if (!subscriber) throw new Error("expected a subscriber"); - const replacement = origin.createBroadcast(path); - replacement.announce(); + const replacement = origin.route(path); // The origin closes the old producer itself, whoever still holds a handle on it. expect(first.closed.peek()).toBeNull(); // Its stale publication never displaces or retracts the replacement. - expect(() => publication.announce({ instance: INSTANCE })).toThrow("broadcast is closed"); - publication.unannounce(); + expect(() => publication.announce()).toThrow("broadcast is closed"); + publication.withdraw(); const current = await routed(consumer, path); expect(readsFrom(current, replacement.broadcast)).toBe(true); current?.close(); @@ -438,7 +441,7 @@ test("a remote entry resolves by path and retracts on dispose", async () => { // Announced streams include remote entries. const announced = consumer.routes(); - expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", route: Route.default }); + expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", route: RouteInfo.default }); dispose(); expect(await announced.next()).toMatchObject({ prefix: path, kind: "end" }); @@ -490,7 +493,7 @@ test("a local publish shadows a remote entry", async () => { // One path, one announcement, even though both tables route it. const announced = consumer.routes(); - expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", route: Route.default }); + expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", route: RouteInfo.default }); // Dropping the local publish falls back to the remote entry without a retraction. local.close(); @@ -719,7 +722,7 @@ test("an identical reconnect restarts without an instance and is quiet with one" const consumer = origin.consume(); const path = Path.from("room"); const announced = consumer.routes(); - const route = Route.normalize({ instance, hops: [PEER] }); + const route = RouteInfo.normalize({ instance, hops: [PEER] }); const old = wireOf(origin).receive(path, route); expect(await announced.next()).toMatchObject({ prefix: path, kind: "start" }); @@ -730,7 +733,7 @@ test("an identical reconnect restarts without an instance and is quiet with one" // Retracting the stale twin is quiet, and a re-price of the winner is an update. old.close(); - fresh.updateRoute({ ...route, cost: 5n }); + wireOf(fresh).update({ ...route, cost: 5n }); expect(await announced.next()).toMatchObject({ prefix: path, kind: "update", route: { cost: 5n } }); fresh.close(); @@ -1024,47 +1027,56 @@ test("a seeded route still notifies when it retracts", async () => { origin.close(); }); -test("createBroadcast is invisible to everyone until announce", async () => { +test("a hidden route is invisible to everyone until announce", async () => { const origin = new Producer(); const consumer = origin.consume(); const path = Path.from("room"); - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; + const broadcastRoute = origin.route(path, { hidden: true, cost: 4n }); + const broadcast = broadcastRoute.broadcast; expect(wireOf(consumer).routes(path)).toBe(false); expect(wireOf(consumer).advertised.peek()?.has(path)).toBe(false); const request = consumer.request(path); expect(request.active.peek()).toBeUndefined(); const announced = consumer.routes(); - broadcastPublication.announce({ cost: 4n }); + expect(broadcastRoute.announced).toBe(false); + broadcastRoute.announce(); + expect(broadcastRoute.announced).toBe(true); expect(wireOf(consumer).routes(path)).toBe(true); expect(wireOf(consumer).advertised.peek()?.has(path)).toBe(true); expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", - route: { hops: [], cost: 4n }, + route: { instance: broadcastRoute.instance, hops: [], cost: 4n }, }); const first = request.active.peek(); - expect(first).toBeDefined(); + expect(first?.instance).toBe(broadcastRoute.instance); // Off the air for local consumers and peers alike, which ends the request on it. - broadcastPublication.unannounce(); + broadcastRoute.withdraw(); expect(wireOf(consumer).routes(path)).toBe(false); expect(wireOf(consumer).advertised.peek()?.has(path)).toBe(false); expect(await announced.next()).toMatchObject({ prefix: path, kind: "end" }); expect(request.active.peek()).toBeUndefined(); expect(request.closed.peek()).toBeInstanceOf(Error); - // Back on the air for a fresh request, through a fresh handle. - broadcastPublication.announce(); - expect(await announced.next()).toMatchObject({ prefix: path, kind: "start" }); + // Back on the air for a fresh request, through a fresh handle, continuing the same instance. + const instance = broadcastRoute.instance; + broadcastRoute.announce(); + expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", route: { instance } }); const fresh = consumer.request(path); const again = fresh.active.peek(); expect(again).toBeDefined(); expect(again).not.toBe(first); + expect(again?.instance).toBe(instance); + // Closing the broadcast retracts the route at once, for good. broadcast.close(); + expect(broadcastRoute.announced).toBe(false); + expect(wireOf(consumer).routes(path)).toBe(false); + expect(() => broadcastRoute.announce()).toThrow("broadcast is closed"); + expect(() => broadcastRoute.setCost(1n)).toThrow("broadcast is closed"); expect(await announced.next()).toMatchObject({ prefix: path, kind: "end" }); fresh.close(); request.close(); @@ -1072,6 +1084,90 @@ test("createBroadcast is invisible to everyone until announce", async () => { origin.close(); }); +test("closing the origin ends a hidden or withdrawn prefix route's requests", async () => { + const origin = new Producer(); + const hidden = origin.routePrefix(Path.from("hidden"), { hidden: true }); + const withdrawn = origin.routePrefix(Path.from("withdrawn")); + withdrawn.withdraw(); + const pending = [hidden.requested().next(), withdrawn.requested().next()]; + + origin.close(); + for (const next of await Promise.all(pending)) expect(next.done).toBe(true); +}); + +test("a prefix route refuses to announce or re-price once its origin closed, like an exact one", () => { + const origin = new Producer(); + const prefix = origin.routePrefix(Path.from("live")); + const exact = origin.route(Path.from("room")); + origin.close(); + expect(prefix.announced).toBe(false); + expect(() => prefix.announce()).toThrow("origin is closed"); + expect(() => prefix.setCost(1n)).toThrow("origin is closed"); + expect(() => exact.announce()).toThrow(); + expect(() => exact.setCost(1n)).toThrow(); +}); + +test("a prefix route can start hidden, withdraw and come back while it keeps yielding requests", async () => { + const origin = new Producer(); + const consumer = origin.consume(); + const prefix = Path.from("jobs"); + const path = Path.from("jobs/a"); + const route = origin.routePrefix(prefix, { hidden: true, cost: 3n }); + expect(() => route.broadcast).toThrow("a prefix route owns no broadcast"); + expect(route.announced).toBe(false); + expect(wireOf(consumer).routes(path)).toBe(false); + const requests = route.requested(); + + route.announce(); + expect(route.announced).toBe(true); + expect(wireOf(consumer).advertised.peek()?.get(prefix)?.[0]?.route).toEqual( + RouteInfo.normalize({ instance: route.instance, cost: 3n }), + ); + const first = consumer.request(path); + const asked = (await requests.next()).value; + if (!asked) throw new Error("expected a request"); + + // Withdrawn, the route answers nothing: the handler's late answer is dropped, and the request + // waits for a route, as it would between reconnects. + route.withdraw(); + expect(route.announced).toBe(false); + expect(wireOf(consumer).routes(path)).toBe(false); + const dropped = new BroadcastProducer(); + asked.serve(dropped); + await settle(); + expect(first.active.peek()).toBeUndefined(); + + // Back under the same instance, the same iterator yields the request again. + const instance = route.instance; + route.announce(); + expect(route.instance).toBe(instance); + const second = consumer.request(path); + const next = (await requests.next()).value; + if (!next) throw new Error("expected another request"); + const source = new BroadcastProducer(); + next.serve(source); + await settle(); + for (const request of [first, second]) expect(request.active.peek()?.instance).toBe(instance); + + first.close(); + second.close(); + dropped.close(); + route.close(); + expect((await requests.next()).done).toBe(true); + expect(() => route.announce()).toThrow("route is closed"); + source.close(); + origin.close(); +}); + +test("an exact route yields no requests", async () => { + const origin = new Producer(); + const route = origin.route(Path.from("room")); + expect((await route.requested().next()).done).toBe(true); + route.close(); + expect(route.broadcast.closed.peek()).toBeNull(); + origin.close(); +}); + test("a request prefers a cheaper received route over an announced local broadcast", async () => { const origin = new Producer(); const consumer = origin.consume(); @@ -1081,11 +1177,10 @@ test("a request prefers a cheaper received route over an announced local broadca origin, path, provider(upstream), - Route.normalize({ instance: INSTANCE, hops: [PEER], cost: 1n }), + RouteInfo.normalize({ instance: INSTANCE, hops: [PEER], cost: 1n }), ); - const localPublication = origin.createBroadcast(path); - const local = localPublication.broadcast; - localPublication.announce({ instance: INSTANCE, cost: 3n }); + const localRoute = origin.route(path, { instance: INSTANCE, cost: 3n }); + const local = localRoute.broadcast; // The cheaper route is served on demand, so it resolves only once its handler answers. const request = consumer.request(path); @@ -1098,7 +1193,7 @@ test("a request prefers a cheaper received route over an announced local broadca // Re-priced below it, the local broadcast of the same instance wins at once: the request's // broadcast stays, and its tracks read the local one. - localPublication.announce({ instance: INSTANCE, cost: 0n }); + localRoute.setCost(0n); expect(await announced.next()).toMatchObject({ prefix: path, kind: "update", @@ -1125,16 +1220,25 @@ test("the cheapest received route competes with the local broadcast, not the new served.push(name); return upstream.consume(); }; - const cheap = serve(origin, path, via("cheap"), Route.normalize({ instance: INSTANCE, hops: [PEER], cost: 1n })); - const pricey = serve(origin, path, via("pricey"), Route.normalize({ instance: INSTANCE, hops: [PEER], cost: 10n })); - const localPublication = origin.createBroadcast(path); - const local = localPublication.broadcast; - localPublication.announce({ instance: INSTANCE, cost: 5n }); + const cheap = serve( + origin, + path, + via("cheap"), + RouteInfo.normalize({ instance: INSTANCE, hops: [PEER], cost: 1n }), + ); + const pricey = serve( + origin, + path, + via("pricey"), + RouteInfo.normalize({ instance: INSTANCE, hops: [PEER], cost: 10n }), + ); + const localRoute = origin.route(path, { instance: INSTANCE, cost: 5n }); + const local = localRoute.broadcast; await new Promise((resolve) => setImmediate(resolve)); expect((await announcedView(consumer)).peek().get(path)).toEqual( - Route.normalize({ instance: INSTANCE, hops: [PEER], cost: 1n }), + RouteInfo.normalize({ instance: INSTANCE, hops: [PEER], cost: 1n }), ); const request = consumer.request(path); await settle(); @@ -1154,7 +1258,7 @@ test("the cheapest received route competes with the local broadcast, not the new test("a handle serves a request under live", async () => { const origin = new Producer(); const consumer = origin.consume(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); expect(await consumer.routes().next()).toMatchObject({ prefix: Path.from("live"), kind: "start" }); @@ -1181,7 +1285,7 @@ test("a handle serves a request under live", async () => { test("an originated route serves held content a session delivered", async () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const it = handle.requested(); const pending = wireOf(origin.consume()).demand(Path.from("live/cam")); const { value: req } = await it.next(); @@ -1219,10 +1323,10 @@ test("a received route still serves a broadcast a session delivered", async () = test("a re-priced route is delivered as an update", async () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const announced = origin.consume().routes(); expect(await announced.next()).toMatchObject({ prefix: Path.from("live"), kind: "start" }); - handle.updateRoute({ cost: 5n }); + handle.setCost(5n); expect(await announced.next()).toMatchObject({ prefix: Path.from("live"), kind: "update" }); handle.close(); expect(await announced.next()).toMatchObject({ prefix: Path.from("live"), kind: "end" }); @@ -1232,7 +1336,7 @@ test("a re-priced route is delivered as an update", async () => { test("an accepted dynamic broadcast is retired when it closes, and its handle resumes", async () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const path = Path.from("live/cam"); const request = origin.request(path); const it = handle.requested(); @@ -1266,7 +1370,7 @@ test("an accepted dynamic broadcast is retired when it closes, and its handle re test("reject surfaces the error from demand", async () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const consumer = origin.consume(); const it = handle.requested(); const pending = wireOf(consumer).demand(Path.from("live/cam")); @@ -1283,11 +1387,11 @@ test("a peer is offered and served the cheapest originated route", async () => { const origin = new Producer(); const consumer = origin.consume(); const prefix = Path.from("live"); - const cheap = origin.requestsRoute(prefix, { instance: INSTANCE, cost: 1n }); - const pricey = origin.requestsRoute(prefix, { instance: INSTANCE, cost: 10n }); + const cheap = origin.routePrefix(prefix, { instance: INSTANCE, cost: 1n }); + const pricey = origin.routePrefix(prefix, { instance: INSTANCE, cost: 10n }); expect(wireOf(consumer).advertised.peek()?.get(prefix)?.[0]?.route).toEqual( - Route.normalize({ instance: INSTANCE, cost: 1n }), + RouteInfo.normalize({ instance: INSTANCE, cost: 1n }), ); const pending = wireOf(consumer).demand(Path.from("live/cam")); const { value: req } = await cheap.requested().next(); @@ -1296,15 +1400,14 @@ test("a peer is offered and served the cheapest originated route", async () => { expect(await pending).toBeDefined(); // An exact-path local broadcast competes with them on cost too. - const localPublication = origin.createBroadcast(prefix); - const local = localPublication.broadcast; - localPublication.announce({ instance: INSTANCE, cost: 5n }); + const localRoute = origin.route(prefix, { instance: INSTANCE, cost: 5n }); + const local = localRoute.broadcast; expect(wireOf(consumer).advertised.peek()?.get(prefix)?.[0]?.route).toEqual( - Route.normalize({ instance: INSTANCE, cost: 1n }), + RouteInfo.normalize({ instance: INSTANCE, cost: 1n }), ); - localPublication.announce({ instance: INSTANCE, cost: 0n }); + localRoute.setCost(0n); expect(wireOf(consumer).advertised.peek()?.get(prefix)?.[0]?.route).toEqual( - Route.normalize({ instance: INSTANCE, cost: 0n }), + RouteInfo.normalize({ instance: INSTANCE, cost: 0n }), ); local.close(); @@ -1316,7 +1419,7 @@ test("a peer is offered and served the cheapest originated route", async () => { test("a shared reject still surfaces from demand", async () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const consumer = origin.consume(); const it = handle.requested(); @@ -1338,7 +1441,7 @@ test("a shared reject still surfaces from demand", async () => { test("a request refusal does not keep demand from asking again", async () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const consumer = origin.consume(); const it = handle.requested(); @@ -1362,7 +1465,7 @@ test("a request refusal does not keep demand from asking again", async () => { test("advancing requested without settling rejects the previous request", async () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const consumer = origin.consume(); const it = handle.requested(); @@ -1386,7 +1489,7 @@ test("advancing requested without settling rejects the previous request", async test("a rejected request is not asked of the same route again", async () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const it = handle.requested(); const request = origin.request(Path.from("live/cam")); @@ -1421,7 +1524,7 @@ test("an outranked route keeps serving until its replacement answers", async () const older = new BroadcastProducer(); const keepOlder = older.consume(); - const disposeOlder = serve(origin, path, () => keepOlder.clone(), Route.normalize({ instance: INSTANCE })); + const disposeOlder = serve(origin, path, () => keepOlder.clone(), RouteInfo.normalize({ instance: INSTANCE })); const request = consumer.request(path); await settle(); @@ -1541,16 +1644,21 @@ test("a request on a replaced instance fails over to another route of it", async const primary = new BroadcastProducer(); const keepPrimary = primary.consume(); - const disposePrimary = serve(origin, path, () => keepPrimary.clone(), Route.normalize({ instance: INSTANCE })); + const disposePrimary = serve(origin, path, () => keepPrimary.clone(), RouteInfo.normalize({ instance: INSTANCE })); const replica = new BroadcastProducer(); - const disposeReplica = serve(origin, path, provider(replica), Route.normalize({ instance: INSTANCE, cost: 5n })); + const disposeReplica = serve( + origin, + path, + provider(replica), + RouteInfo.normalize({ instance: INSTANCE, cost: 5n }), + ); const request = consumer.request(path); await settle(); const first = request.active.peek(); expect(first).toBeDefined(); const restarted = new BroadcastProducer(); - const disposeRestarted = serve(origin, path, provider(restarted), Route.normalize({ instance: newer })); + const disposeRestarted = serve(origin, path, provider(restarted), RouteInfo.normalize({ instance: newer })); await settle(); expect(request.active.peek()).toBe(first); @@ -1589,17 +1697,16 @@ test("a request on a replaced instance fails over to a local replica of it", asy const primary = new BroadcastProducer(); const keepPrimary = primary.consume(); - const disposePrimary = serve(origin, path, () => keepPrimary.clone(), Route.normalize({ instance: INSTANCE })); - const localPublication = origin.createBroadcast(path); - const local = localPublication.broadcast; - localPublication.announce({ instance: INSTANCE, cost: 5n }); + const disposePrimary = serve(origin, path, () => keepPrimary.clone(), RouteInfo.normalize({ instance: INSTANCE })); + const localRoute = origin.route(path, { instance: INSTANCE, cost: 5n }); + const local = localRoute.broadcast; const request = consumer.request(path); await settle(); const first = request.active.peek(); expect(first).toBeDefined(); const restarted = new BroadcastProducer(); - const disposeRestarted = serve(origin, path, provider(restarted), Route.normalize({ instance: newer })); + const disposeRestarted = serve(origin, path, provider(restarted), RouteInfo.normalize({ instance: newer })); await settle(); expect(request.active.peek()).toBe(first); @@ -1632,10 +1739,9 @@ test("a stale takeover's refusal leaves a request whose source came back", async const path = Path.from("resumed"); const newer = Instance.parse("01900000-0000-7000-8000-000000000002"); - const localPublication = origin.createBroadcast(path); - const local = localPublication.broadcast; - localPublication.announce({ instance: INSTANCE, cost: 2n }); - const standby = wireOf(origin).receive(path, Route.normalize({ instance: INSTANCE, cost: 5n })); + const localRoute = origin.route(path, { instance: INSTANCE, cost: 2n }); + const local = localRoute.broadcast; + const standby = wireOf(origin).receive(path, RouteInfo.normalize({ instance: INSTANCE, cost: 5n })); const asked = standby.requested(); const request = consumer.request(path); await settle(); @@ -1644,14 +1750,19 @@ test("a stale takeover's refusal leaves a request whose source came back", async const restarted = new BroadcastProducer(); // Another instance, cheaper, wins new requests. - const disposeRestarted = serve(origin, path, provider(restarted), Route.normalize({ instance: newer, cost: 1n })); + const disposeRestarted = serve( + origin, + path, + provider(restarted), + RouteInfo.normalize({ instance: newer, cost: 1n }), + ); await settle(); expect(request.active.peek()).toBe(first); // The local broadcast steps away, so the standby is asked to take over; it comes back first. - localPublication.unannounce(); + localRoute.withdraw(); const takeover = await asked.next(); - localPublication.announce({ instance: INSTANCE, cost: 2n }); + localRoute.announce(); await settle(); takeover.value?.reject(new Error("too late")); await settle(); @@ -1672,7 +1783,7 @@ test("a request ends when its winning source goes, even with a standby", async ( const path = Path.from("standby"); const standby = new BroadcastProducer(); - const disposeStandby = serve(origin, path, provider(standby), Route.normalize({ cost: 5n })); + const disposeStandby = serve(origin, path, provider(standby), RouteInfo.normalize({ cost: 5n })); const winner = new BroadcastProducer(); const keepWinner = winner.consume(); const disposeWinner = serve(origin, path, () => keepWinner.clone()); @@ -1702,8 +1813,8 @@ test("a request ends when its winning source goes, even with a standby", async ( test("a refusal is terminal, never falling through to a broader route", async () => { const origin = new Producer(); const consumer = origin.consume(); - const narrow = origin.requestsRoute(Path.from("live")); - const wide = origin.requestsRoute(Path.from("")); + const narrow = origin.routePrefix(Path.from("live")); + const wide = origin.routePrefix(Path.from("")); const wideRequests = wide.requested(); const wideAsked = wideRequests.next(); @@ -1730,7 +1841,7 @@ test("a better route's refusal ends a served request", async () => { const consumer = origin.consume(); const served = new BroadcastProducer(); // One instance, so the narrower route serves the same instance and the request follows it. - const disposeWide = serve(origin, Path.from(""), provider(served), Route.normalize({ instance: INSTANCE })); + const disposeWide = serve(origin, Path.from(""), provider(served), RouteInfo.normalize({ instance: INSTANCE })); const request = consumer.request(Path.from("live/cam")); await settle(); @@ -1739,8 +1850,8 @@ test("a better route's refusal ends a served request", async () => { // The narrower route is asked while the broad one keeps serving, then says no. A // costlier sibling at the same prefix could serve, but is never asked. - const narrow = origin.requestsRoute(Path.from("live"), { instance: INSTANCE, cost: 1n }); - const sibling = origin.requestsRoute(Path.from("live"), { instance: INSTANCE, cost: 2n }); + const narrow = origin.routePrefix(Path.from("live"), { instance: INSTANCE, cost: 1n }); + const sibling = origin.routePrefix(Path.from("live"), { instance: INSTANCE, cost: 2n }); const siblingRequests = sibling.requested(); const siblingAsked = siblingRequests.next(); const { value: req } = await narrow.requested().next(); @@ -1765,14 +1876,14 @@ test("a better route's refusal ends a served request", async () => { test("a refusal from a superseded route does not end the request", async () => { const origin = new Producer(); const consumer = origin.consume(); - const wide = origin.requestsRoute(Path.from("")); + const wide = origin.routePrefix(Path.from("")); const wideRequests = wide.requested(); const request = consumer.request(Path.from("live/cam")); const { value: stale } = await wideRequests.next(); // A narrower route takes over the pending request before the broad one answers. - const narrow = origin.requestsRoute(Path.from("live")); + const narrow = origin.routePrefix(Path.from("live")); const { value: req } = await narrow.requested().next(); stale?.reject(new Error("unserved")); await settle(); @@ -1794,7 +1905,7 @@ test("a refusal from a superseded route does not end the request", async () => { test("a refusal from a route a local broadcast superseded does not end the request", async () => { const origin = new Producer(); const consumer = origin.consume(); - const wide = origin.requestsRoute(Path.from("live")); + const wide = origin.routePrefix(Path.from("live")); const wideRequests = wide.requested(); const request = consumer.request(Path.from("live/cam")); @@ -1820,7 +1931,7 @@ test("a refusal from a route a local broadcast superseded does not end the reque test("close rejects queued requests as unroutable", async () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live")); + const handle = origin.routePrefix(Path.from("live")); const waiting = handle.requested().next(); const request = origin.request(Path.from("live/cam")); const { value: req } = await waiting; @@ -1858,9 +1969,9 @@ test("announced lists full names while covering views and session advertisements const origin = new Producer(); const patterns = new Path.Patterns([Path.Pattern.parse("*.hang"), Path.Pattern.parse("**/*.chat")]); const reader = origin.scope(Path.from("project"), patterns).consume(); - const cam = origin.requestsRoute(Path.from("project/cam.hang")); - const overlap = origin.requestsRoute(Path.from("project/room/mic.hang")); - const chat = origin.requestsRoute(Path.from("project/lobby.chat")); + const cam = origin.routePrefix(Path.from("project/cam.hang")); + const overlap = origin.routePrefix(Path.from("project/room/mic.hang")); + const chat = origin.routePrefix(Path.from("project/lobby.chat")); const selected = await announcedView(reader); const covering = await announcedView(reader, undefined, { covering: true }); const all = [Path.from("cam.hang"), Path.from("lobby.chat"), Path.from("room/mic.hang")]; @@ -1868,10 +1979,10 @@ test("announced lists full names while covering views and session advertisements expect([...covering.peek().keys()].sort()).toEqual(all); expect(Array.from(wireOf(reader).advertised.peek()?.keys() ?? []).sort()).toEqual(all); - const nested = origin.requestsRoute(Path.from("project/room/lobby.chat")); + const nested = origin.routePrefix(Path.from("project/room/lobby.chat")); await new Promise((resolve) => setImmediate(resolve)); expect(selected.peek().has(Path.from("room/lobby.chat"))).toBe(true); - overlap.updateRoute({ cost: 2n }); + overlap.setCost(2n); overlap.close(); nested.close(); await new Promise((resolve) => setImmediate(resolve)); @@ -1891,7 +2002,7 @@ test("announced filters before rooting and retains lifecycle, routing and watch const interests: string[] = []; const unlisten = wireOf(origin).interests((prefix, wanted) => interests.push(`${wanted ? "+" : "-"}${prefix}`)); const source = new BroadcastProducer(); - const broad = origin.requestsRoute(Path.from("room")); + const broad = origin.routePrefix(Path.from("room")); const stream = reader.routes(); const events = stream[Symbol.asyncIterator](); const covering = await announcedView(reader, undefined, { covering: true }); @@ -1906,13 +2017,13 @@ test("announced filters before rooting and retains lifecycle, routing and watch expect(request.active.peek()).toBeDefined(); request.close(); - const exact = origin.requestsRoute(root, { instance: INSTANCE }); + const exact = origin.routePrefix(root, { instance: INSTANCE }); expect(await events.next()).toMatchObject({ value: { kind: "start", prefix: Path.empty(), captures: expect.any(Array) }, }); - exact.updateRoute({ instance: INSTANCE, cost: 2n }); + wireOf(exact).update({ instance: INSTANCE, cost: 2n }); expect(await events.next()).toMatchObject({ value: { kind: "update", route: { cost: 2n } } }); - exact.updateRoute({ instance: Instance.random() }); + wireOf(exact).update({ instance: Instance.random() }); expect(await events.next()).toMatchObject({ value: { kind: "restart" } }); exact.close(); expect(await events.next()).toMatchObject({ value: { kind: "end" } }); @@ -2054,11 +2165,11 @@ test("a rooted producer shares the table and enforces its pattern union", async await new Promise((resolve) => setImmediate(resolve)); expect(request.active.peek()).toBeDefined(); await new Promise((resolve) => setImmediate(resolve)); - expect(() => scoped.createBroadcast(Path.from("other")).broadcast).toThrow("outside the origin scope"); + expect(() => scoped.route(Path.from("other"), { hidden: true }).broadcast).toThrow("outside the origin scope"); await new Promise((resolve) => setImmediate(resolve)); expect(() => scoped.request(Path.from("room/alice/deep"))).toThrow("outside the origin scope"); await new Promise((resolve) => setImmediate(resolve)); - expect(() => scoped.requestsRoute(Path.from("other"))).toThrow("outside the origin scope"); + expect(() => scoped.routePrefix(Path.from("other"))).toThrow("outside the origin scope"); await new Promise((resolve) => setImmediate(resolve)); expect(() => scoped.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("other/**")]))).toThrow( "do not overlap", @@ -2070,7 +2181,7 @@ test("a rooted producer shares the table and enforces its pattern union", async await new Promise((resolve) => setImmediate(resolve)); expect([...(await announcedView(nested)).peek().keys()]).toEqual([Path.from("alice")]); await new Promise((resolve) => setImmediate(resolve)); - expect(() => nested.createBroadcast(Path.from("alice/deep")).broadcast).toThrow("outside the origin scope"); + expect(() => nested.route(Path.from("alice/deep"), { hidden: true }).broadcast).toThrow("outside the origin scope"); const announced = nested.routes(); await new Promise((resolve) => setImmediate(resolve)); expect(await announced.next()).toMatchObject({ kind: "start", prefix: Path.from("alice") }); @@ -2086,8 +2197,8 @@ test("closing a derived handle releases only what it registered", async () => { const scoped = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from("room"))])); const wide = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.all()])); const inside = publish(scoped, Path.from("room/alice")); - const claim = scoped.requests(Path.from("room/claim")); - const ranked = wide.requests(Path.from("ranked")); + const claim = scoped.routePrefix(Path.from("room/claim")); + const ranked = wide.routePrefix(Path.from("ranked")); const peer = serve(scoped, Path.from("room/peer"), provider(new BroadcastProducer())); scoped.close(); @@ -2100,8 +2211,8 @@ test("closing a derived handle releases only what it registered", async () => { expect([...routes.keys()]).toEqual([Path.from("lobby")]); // A released handle refuses new work, so a borrower notices instead of publishing into nothing. - expect(() => scoped.createBroadcast(Path.from("room/late")).broadcast).toThrow("origin handle is closed"); - scoped.requests(Path.from("room/late")).close(); + expect(() => scoped.route(Path.from("room/late"), { hidden: true }).broadcast).toThrow("origin handle is closed"); + scoped.routePrefix(Path.from("room/late")).close(); expect((await announcedView(origin)).peek().has(Path.from("room/late"))).toBe(false); // The owner and fresh handles keep working. @@ -2123,9 +2234,8 @@ test("a broadcast a derived handle released cannot announce again", async () => const consumer = origin.consume(); const scoped = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.all()])); const path = Path.from("room"); - const publication = scoped.createBroadcast(path); + const publication = scoped.route(path); const broadcast = publication.broadcast; - publication.announce(); const held = await routed(consumer, path); scoped.close(); @@ -2200,9 +2310,8 @@ test("closing a derived handle withdraws the sessions and answers attached throu test("a scoped dynamic only serves allowed paths and presents relative requests", async () => { const origin = new Producer(); const scoped = origin.scope(Path.from("tenant"), new Path.Patterns([Path.Pattern.parse("room/*/chat")])); - const dynamic = scoped.requestsRoute(Path.from("room")); + const dynamic = scoped.routePrefix(Path.from("room")); await new Promise((resolve) => setImmediate(resolve)); - expect(dynamic.prefix).toBe(Path.from("room")); const denied = origin.request(Path.from("tenant/room/alice/video")); await new Promise((resolve) => setImmediate(resolve)); expect(denied.active.peek()).toBeUndefined(); @@ -2215,7 +2324,7 @@ test("a scoped dynamic only serves allowed paths and presents relative requests" pending.value.serve(broadcast); await new Promise((resolve) => setImmediate(resolve)); expect(request.active.peek()).toBeDefined(); - dynamic.updateRoute({ cost: 2n }); + dynamic.setCost(2n); await new Promise((resolve) => setImmediate(resolve)); expect((await announcedView(origin)).peek().get(Path.from("tenant/room"))?.cost).toBe(2n); await requests.return?.(); @@ -2248,7 +2357,7 @@ test("a scoped dynamic is announced only to readers its scope can serve", async const origin = new Producer(); const dynamic = origin .scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("*/chat")])) - .requestsRoute(Path.empty()); + .routePrefix(Path.empty()); const chat = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/chat")])); const video = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/video")])); await new Promise((resolve) => setImmediate(resolve)); @@ -2265,8 +2374,8 @@ test("a scoped dynamic is announced only to readers its scope can serve", async test("a rooted reader presents the most specific covering route", async () => { const origin = new Producer(); - const narrow = origin.requestsRoute(Path.from("room/alice"), { cost: 9n }); - const broad = origin.requestsRoute(Path.from("room"), { cost: 1n }); + const narrow = origin.routePrefix(Path.from("room/alice"), { cost: 9n }); + const broad = origin.routePrefix(Path.from("room"), { cost: 1n }); const rooted = origin.scope(Path.from("room/alice"), new Path.Patterns([Path.Pattern.all()])); await new Promise((resolve) => setImmediate(resolve)); expect((await announcedView(rooted)).peek().get(Path.empty())?.cost).toBe(9n); @@ -2280,8 +2389,8 @@ test("a rooted reader presents the most specific covering route", async () => { test("a scoped reader picks the best route its scope can see at a prefix", async () => { const origin = new Producer(); const scoped = (pattern: string) => origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse(pattern)])); - const chat = scoped("*/chat").requestsRoute(Path.empty(), { cost: 1n }); - const video = scoped("*/video").requestsRoute(Path.empty(), { cost: 5n }); + const chat = scoped("*/chat").routePrefix(Path.empty(), { cost: 1n }); + const video = scoped("*/video").routePrefix(Path.empty(), { cost: 5n }); const reader = scoped("room/video"); await new Promise((resolve) => setImmediate(resolve)); @@ -2311,10 +2420,9 @@ test("a scoped reader sees a local broadcast that only loses to a route outside const origin = new Producer(); const chat = origin .scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/*/chat")])) - .requestsRoute(Path.from("room/alice"), { instance: INSTANCE, cost: 0n }); - const localPublication = origin.createBroadcast(Path.from("room/alice")); - const local = localPublication.broadcast; - localPublication.announce({ instance: INSTANCE, cost: 5n }); + .routePrefix(Path.from("room/alice"), { instance: INSTANCE, cost: 0n }); + const localRoute = origin.route(Path.from("room/alice"), { instance: INSTANCE, cost: 5n }); + const local = localRoute.broadcast; const reader = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/*")])); await new Promise((resolve) => setImmediate(resolve)); @@ -2346,7 +2454,7 @@ test("broadcast handles carry the path they were created or requested at", async expect(clone?.path).toBe(Path.from("room/alice")); // A dynamic handler's standalone broadcast is named by the request, too. - const dynamic = origin.requestsRoute(Path.from("live")); + const dynamic = origin.routePrefix(Path.from("live")); const request = origin.request(Path.from("live/bob")); const pending = await dynamic.requested().next(); const served = new BroadcastProducer(); @@ -2367,9 +2475,8 @@ test("a higher epoch of a dynamic route supersedes a cheaper local broadcast of const origin = new Producer(); const path = Path.from("camera"); const instance = Instance.random(); - const localPublication = origin.createBroadcast(path); - localPublication.announce({ instance, epoch: 1n, cost: 0n }); - const dynamic = origin.requestsRoute(path, { instance, epoch: 2n, cost: 10n }); + const localRoute = origin.route(path, { instance, epoch: 1n, cost: 0n }); + const dynamic = origin.routePrefix(path, { instance, epoch: 2n, cost: 10n }); const served = new BroadcastProducer(); const requests = dynamic.requested(); const request = origin.consume().request(path); @@ -2381,7 +2488,7 @@ test("a higher epoch of a dynamic route supersedes a cheaper local broadcast of request.close(); await requests.return?.(); dynamic.close(); - localPublication.broadcast.close(); + localRoute.broadcast.close(); served.close(); origin.close(); }); @@ -2390,10 +2497,9 @@ test("a higher epoch that is not the best route still supersedes a local broadca const origin = new Producer(); const path = Path.from("camera"); const stale = Instance.random(); - const localPublication = origin.createBroadcast(path); - localPublication.announce({ instance: stale, epoch: 1n, cost: 0n }); - const newer = origin.requestsRoute(path, { instance: stale, epoch: 2n, cost: 10n }); - const other = origin.requestsRoute(path, { instance: Instance.random(), cost: 5n }); + const localRoute = origin.route(path, { instance: stale, epoch: 1n, cost: 0n }); + const newer = origin.routePrefix(path, { instance: stale, epoch: 2n, cost: 10n }); + const other = origin.routePrefix(path, { instance: Instance.random(), cost: 5n }); const served = new BroadcastProducer(); const requests = other.requested(); const request = origin.consume().request(path); @@ -2406,7 +2512,7 @@ test("a higher epoch that is not the best route still supersedes a local broadca await requests.return?.(); other.close(); newer.close(); - localPublication.broadcast.close(); + localRoute.broadcast.close(); served.close(); origin.close(); }); @@ -2415,23 +2521,22 @@ test("a publisher weighs a local broadcast against the routes it may forward onl const origin = new Producer(); const path = Path.from("camera"); const instance = Instance.random(); - const localPublication = origin.createBroadcast(path); - localPublication.announce({ instance, epoch: 1n, cost: 0n }); - const originated = origin.requestsRoute(path, { cost: 5n }); + const localRoute = origin.route(path, { instance, epoch: 1n, cost: 0n }); + const originated = origin.routePrefix(path, { cost: 5n }); // A session delivered the higher epoch, which a publisher never forwards back out. const received = wireOf(origin).receive(path, { instance, epoch: 2n, cost: 10n, hops: [PEER] }); expect(wireOf(origin.consume()).local(path, instance)).toBeDefined(); received.close(); originated.close(); - localPublication.broadcast.close(); + localRoute.broadcast.close(); origin.close(); }); test("a scope's merged covering prefixes never supersede across prefixes", async () => { const origin = new Producer(); const instance = Instance.random(); - const room = origin.requestsRoute(Path.from("room"), { instance, epoch: 2n }); - const video = origin.requestsRoute(Path.from("room/video"), { instance, epoch: 1n }); + const room = origin.routePrefix(Path.from("room"), { instance, epoch: 2n }); + const video = origin.routePrefix(Path.from("room/video"), { instance, epoch: 1n }); const reader = origin.scope(Path.from("room/video"), new Path.Patterns([Path.Pattern.all()])).consume(); await settle(); const table = wireOf(reader).advertised.peek(); @@ -2448,14 +2553,14 @@ test("supersession only counts routes the reader can see", async () => { const instance = Instance.random(); const video = origin .scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("*/video")])) - .requestsRoute(Path.empty(), { instance, epoch: 1n }); + .routePrefix(Path.empty(), { instance, epoch: 1n }); const live = await announcedView(origin, Path.Pattern.parse("room/video"), { covering: true }); await settle(); expect(live.peek().size).toBe(1); // A higher epoch the reader cannot see never hides the route it can. const chat = origin .scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("*/chat")])) - .requestsRoute(Path.empty(), { instance, epoch: 2n }); + .routePrefix(Path.empty(), { instance, epoch: 2n }); await settle(); expect([...live.peek().values()].map((route) => route.epoch)).toEqual([1n]); chat.close(); @@ -2470,9 +2575,8 @@ test("the newest epoch of an instance is announced in place over a cheaper one", const announced = consumer.routes(); const instance = Instance.random(); - const oldPublication = origin.createBroadcast(path); - const old = oldPublication.broadcast; - oldPublication.announce({ instance, epoch: 1n, cost: 1n }); + const oldRoute = origin.route(path, { instance, epoch: 1n, cost: 1n }); + const old = oldRoute.broadcast; expect(await announced.next()).toMatchObject({ prefix: path, kind: "start" }); // A higher epoch of the same instance supersedes it despite the cost: the same stream. @@ -2498,14 +2602,14 @@ test("demand held across an instance change asks again, unless it named the old const origin = new Producer(); const consumer = origin.consume(); const path = Path.from("live/cam"); - const handle = origin.requestsRoute(Path.from("live"), { instance: INSTANCE }); + const handle = origin.routePrefix(Path.from("live"), { instance: INSTANCE }); const it = handle.requested(); const pinned = wireOf(consumer).demand(path, INSTANCE); const unpinned = wireOf(consumer).demand(path); const { value: req } = await it.next(); // Another instance now serves the route: the old handler's answer is for the old one. - handle.updateRoute({ ...handle.route, instance: NEWER }); + wireOf(handle).update({ ...wireOf(handle).info, instance: NEWER }); req.serve(new BroadcastProducer().consume()); await expect(pinned).rejects.toThrow("unroutable"); @@ -2527,13 +2631,13 @@ test("a demand refused across an instance change does not lose the carried deman const origin = new Producer(); const consumer = origin.consume(); const path = Path.from("live/cam"); - const handle = origin.requestsRoute(Path.from("live"), { instance: INSTANCE }); + const handle = origin.routePrefix(Path.from("live"), { instance: INSTANCE }); const it = handle.requested(); const unpinned = wireOf(consumer).demand(path); const pinned = wireOf(consumer).demand(path, INSTANCE); await it.next(); - handle.updateRoute({ ...handle.route, instance: NEWER }); + wireOf(handle).update({ ...wireOf(handle).info, instance: NEWER }); await expect(pinned).rejects.toThrow("unroutable"); // The replacement's refusal reaches the demand that carried over. (await it.next()).value?.reject(new Error("gone")); @@ -2547,14 +2651,14 @@ test("a demand refused across an instance change does not lose the carried deman test("demand held across an instance round trip still asks again", async () => { const origin = new Producer(); const path = Path.from("live/cam"); - const handle = origin.requestsRoute(Path.from("live"), { instance: INSTANCE }); + const handle = origin.routePrefix(Path.from("live"), { instance: INSTANCE }); const it = handle.requested(); const demanded = wireOf(origin.consume()).demand(path); const { value: req } = await it.next(); // Released by the first change; the instance coming back does not undo that. - handle.updateRoute({ ...handle.route, instance: NEWER }); - handle.updateRoute({ ...handle.route, instance: INSTANCE }); + wireOf(handle).update({ ...wireOf(handle).info, instance: NEWER }); + wireOf(handle).update({ ...wireOf(handle).info, instance: INSTANCE }); req.serve(new BroadcastProducer().consume()); const next = new BroadcastProducer(); @@ -2573,18 +2677,18 @@ test("demand held across an instance round trip still asks again", async () => { test("re-pricing from the current route keeps the instance", () => { const origin = new Producer(); - const handle = origin.requestsRoute(Path.from("live"), { instance: INSTANCE, cost: 5n }); - handle.updateRoute({ ...handle.route, cost: 1n }); - expect(handle.route).toEqual(Route.normalize({ instance: INSTANCE, cost: 1n })); + const handle = origin.routePrefix(Path.from("live"), { instance: INSTANCE, cost: 5n }); + handle.setCost(1n); + expect(wireOf(handle).info).toEqual(RouteInfo.normalize({ instance: INSTANCE, cost: 1n })); - const broadcastPublication = origin.createBroadcast(Path.from("room")); - const broadcast = broadcastPublication.broadcast; - expect(broadcastPublication.route).toBeUndefined(); - broadcastPublication.announce({ instance: INSTANCE, cost: 5n }); - broadcastPublication.announce({ ...broadcastPublication.route, cost: 1n }); - expect(broadcastPublication.route).toEqual(Route.normalize({ instance: INSTANCE, cost: 1n })); - broadcastPublication.unannounce(); - expect(broadcastPublication.route).toBeUndefined(); + const broadcastRoute = origin.route(Path.from("room"), { hidden: true, instance: INSTANCE, cost: 5n }); + const broadcast = broadcastRoute.broadcast; + expect(wireOf(broadcastRoute).info).toBeUndefined(); + broadcastRoute.announce(); + broadcastRoute.setCost(1n); + expect(wireOf(broadcastRoute).info).toEqual(RouteInfo.normalize({ instance: INSTANCE, cost: 1n })); + broadcastRoute.withdraw(); + expect(wireOf(broadcastRoute).info).toBeUndefined(); broadcast.close(); handle.close(); @@ -2595,9 +2699,8 @@ test("a peer naming another instance is refused rather than served a different i const origin = new Producer(); const consumer = origin.consume(); const path = Path.from("room"); - const localPublication = origin.createBroadcast(path); - const local = localPublication.broadcast; - localPublication.announce({ instance: INSTANCE }); + const localRoute = origin.route(path, { instance: INSTANCE }); + const local = localRoute.broadcast; expect(wireOf(consumer).local(path, INSTANCE)).toBeDefined(); const other = Instance.parse("01900000-0000-7000-8000-000000000002"); @@ -2611,18 +2714,16 @@ test("a peer naming another instance is refused rather than served a different i test("a newer instance ends pinned and unpinned requests on the replaced publisher alike", () => { const origin = new Producer(); const path = Path.from("room"); - const first = origin.createBroadcast(path); - first.announce({ instance: INSTANCE }); + const first = origin.route(path, { instance: INSTANCE }); const reader = origin.consume(); const pinned = reader.request(path, { instance: INSTANCE }); const unpinned = reader.request(path); expect(pinned.active.peek()?.instance).toBe(INSTANCE); expect(unpinned.active.peek()?.instance).toBe(INSTANCE); const replacement = Instance.parse("01900000-0000-7000-8000-000000000002"); - const second = origin.createBroadcast(path); - second.announce({ instance: replacement }); - expect(() => first.announce({ instance: INSTANCE })).toThrow("broadcast is closed"); - first.unannounce(); + origin.route(path, { instance: replacement }); + expect(() => first.announce()).toThrow("broadcast is closed"); + first.withdraw(); expect(pinned.active.peek()).toBeUndefined(); // The replaced publisher closed: the unpinned request ends rather than move to the newer one. expect(unpinned.active.peek()).toBeUndefined(); @@ -2642,12 +2743,12 @@ test("a request held across an instance change asks again and never takes the ol const origin = new Producer(); const prefix = Path.from("room"); const path = Path.from("room/cam"); - const dynamic = origin.requestsRoute(prefix, { instance: INSTANCE }); + const dynamic = origin.routePrefix(prefix, { instance: INSTANCE }); const unpinned = origin.consume().request(path); const pinned = origin.consume().request(path, { instance: INSTANCE }); const requests = dynamic.requested(); const old = (await requests.next()).value; - dynamic.updateRoute({ ...dynamic.route, instance: NEWER }); + wireOf(dynamic).update({ ...wireOf(dynamic).info, instance: NEWER }); const current = origin.consume().request(path, { instance: NEWER }); old.serve(new BroadcastProducer().consume()); await settle(); @@ -2675,9 +2776,9 @@ test.each([ const origin = new Producer(); const prefix = Path.from("live"); const path = Path.from("live/cam"); - const dynamic = origin.requestsRoute(prefix, { instance: named }); + const dynamic = origin.routePrefix(prefix, { instance: named }); // A claim naming no instance serves one of its own. - const from = dynamic.route.instance; + const from = dynamic.instance; expect(from).toBeDefined(); if (named !== undefined) expect(from).toBe(named); const to = NEWER; @@ -2698,7 +2799,7 @@ test.each([ expect((await sticky?.recvGroup())?.sequence).toBe(0n); // A re-price at the same instance keeps every handle, and the handler is not asked again. - dynamic.updateRoute({ ...dynamic.route, cost: 5n }); + dynamic.setCost(5n); expect(await announced.next()).toMatchObject({ prefix, kind: "update" }); expect(held.active.peek()).toBe(resolved); const same = origin.consume().request(path); @@ -2707,7 +2808,7 @@ test.each([ const pinned = origin.consume().request(path, { instance: from }); // Another instance is another stream: resolved requests keep the old one. - dynamic.updateRoute({ ...dynamic.route, instance: to }); + wireOf(dynamic).update({ ...wireOf(dynamic).info, instance: to }); expect(await announced.next()).toMatchObject({ prefix, kind: "restart" }); await settle(); expect(held.active.peek()).toBe(resolved); @@ -2762,14 +2863,14 @@ test.each([ test("an instance update does not retain an answer that already closed", async () => { const origin = new Producer(); const path = Path.from("live/cam"); - const dynamic = origin.requestsRoute(Path.from("live"), { instance: INSTANCE }); + const dynamic = origin.routePrefix(Path.from("live"), { instance: INSTANCE }); const requests = dynamic.requested(); const held = origin.consume().request(path); const old = new BroadcastProducer(); (await requests.next()).value.serve(old); old.close(); // The server's closure callback has not removed the answer yet. - dynamic.updateRoute({ instance: NEWER }); + wireOf(dynamic).update({ instance: NEWER }); try { expect(held.closed.peek()).toBeInstanceOf(Error); expect(held.active.peek()).toBeUndefined(); @@ -2790,13 +2891,13 @@ test("an instance update does not retain an answer that already closed", async ( test("an unread resolved request retains its broadcast until its last handle closes", async () => { const origin = new Producer(); const path = Path.from("live/cam"); - const dynamic = origin.requestsRoute(Path.from("live"), { instance: INSTANCE }); + const dynamic = origin.routePrefix(Path.from("live"), { instance: INSTANCE }); const requests = dynamic.requested(); const held = origin.consume().request(path); const old = new SessionBroadcast(); (await requests.next()).value.serve(old); // Change instances before the active getter or its subscription can clone the answer. - dynamic.updateRoute({ instance: NEWER }); + wireOf(dynamic).update({ instance: NEWER }); expect(old.closed.peek()).toBeUndefined(); expect(held.active.peek()?.instance).toBe(INSTANCE); held.close(); @@ -2810,7 +2911,7 @@ test("an unread resolved request retains its broadcast until its last handle clo test("a session's re-request after an instance update asks the handler again", async () => { const origin = new Producer(); const path = Path.from("live/cam"); - const dynamic = origin.requestsRoute(Path.from("live"), { instance: INSTANCE }); + const dynamic = origin.routePrefix(Path.from("live"), { instance: INSTANCE }); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); @@ -2819,7 +2920,7 @@ test("a session's re-request after an instance update asks the handler again", a (await requests.next()).value.serve(old); expect(await before).toBeDefined(); - dynamic.updateRoute({ ...dynamic.route, instance: NEWER }); + wireOf(dynamic).update({ ...wireOf(dynamic).info, instance: NEWER }); const after = wire.demand(path); const next = new BroadcastProducer(); const track = next.createTrack("video"); @@ -2840,8 +2941,8 @@ test("an update does not override route selection: another claim at the instance const origin = new Producer(); const prefix = Path.from("live"); const path = Path.from("live/cam"); - const first = origin.requestsRoute(prefix, { instance: INSTANCE, cost: 1n }); - const second = origin.requestsRoute(prefix, { instance: INSTANCE, cost: 5n }); + const first = origin.routePrefix(prefix, { instance: INSTANCE, cost: 1n }); + const second = origin.routePrefix(prefix, { instance: INSTANCE, cost: 5n }); const firstRequests = first.requested(); const secondRequests = second.requested(); @@ -2854,7 +2955,7 @@ test("an update does not override route selection: another claim at the instance // The first claim moves to another instance priced above the second, which still serves // the old one: the resolved request keeps its answer, and new requests go through the // second claim. - first.updateRoute({ ...first.route, instance: NEWER, cost: 9n }); + wireOf(first).update({ ...wireOf(first).info, instance: NEWER, cost: 9n }); const fresh = origin.consume().request(path); const replacement = new BroadcastProducer(); const track = replacement.createTrack("video"); @@ -2878,14 +2979,13 @@ test("an update does not override route selection: another claim at the instance origin.close(); }); -test("a route naming no instance resolves a handle under the one its publication minted", () => { +test("a route naming no instance resolves a handle under the one it minted", () => { const origin = new Producer(); const path = Path.from("room"); - const broadcast = origin.createBroadcast(path); - broadcast.announce(); + const broadcast = origin.route(path); const request = origin.consume().request(path); - expect(broadcast.route?.instance).toBeDefined(); - expect(request.active.peek()?.instance).toBe(broadcast.route?.instance); + expect(broadcast.instance).toBeDefined(); + expect(request.active.peek()?.instance).toBe(broadcast.instance); request.close(); origin.close(); }); @@ -2893,19 +2993,18 @@ test("a route naming no instance resolves a handle under the one its publication test("public announcements saturate static costs and refuse invalid cost shapes", async () => { const origin = new Producer(); const path = Path.from("priced"); - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; + const broadcastRoute = origin.route(path, { hidden: true }); + const broadcast = broadcastRoute.broadcast; const view = await announcedView(origin); - broadcastPublication.announce({ cost: 2n ** 64n - 1n }); + broadcastRoute.setCost(2n ** 64n - 1n); + broadcastRoute.announce(); await settle(); await new Promise((resolve) => setImmediate(resolve)); expect(view.peek().get(path)?.cost).toBe(2n ** 62n - 1n); await new Promise((resolve) => setImmediate(resolve)); - expect(() => broadcastPublication.announce({ cost: -1n })).toThrow(RangeError); + expect(() => broadcastRoute.setCost(-1n)).toThrow(RangeError); await new Promise((resolve) => setImmediate(resolve)); - expect(() => broadcastPublication.announce({ cost: { warm: 1n, cold: 2n } } as unknown as Route)).toThrow( - RangeError, - ); + expect(() => broadcastRoute.setCost({ warm: 1n, cold: 2n } as unknown as Cost)).toThrow(RangeError); broadcast.close(); origin.close(); }); @@ -2915,14 +3014,14 @@ test("published names refuse navigation segments", () => { try { for (const name of ["room/./cam", "room/../cam", ".", ".."]) { const path = Path.from(name); - expect(() => origin.createBroadcast(path).broadcast).toThrow(); - expect(() => origin.requests(path)).toThrow(); - expect(() => wireOf(origin).receive(path, Route.default)).toThrow(); + expect(() => origin.route(path, { hidden: true }).broadcast).toThrow(); + expect(() => origin.routePrefix(path)).toThrow(); + expect(() => wireOf(origin).receive(path, RouteInfo.default)).toThrow(); } const scoped = origin.scope(Path.from("room/.."), new Path.Patterns([Path.Pattern.all()])); - expect(() => scoped.createBroadcast(Path.from("cam")).broadcast).toThrow(); + expect(() => scoped.route(Path.from("cam"), { hidden: true }).broadcast).toThrow(); for (const path of ["room/.pro/cam", "room/a..b", "room/cam"]) { - origin.createBroadcast(Path.from(path)).broadcast.close(); + origin.route(Path.from(path), { hidden: true }).broadcast.close(); } } finally { origin.close(); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index ca062735965..963a6e40ff4 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -13,9 +13,10 @@ import { Derived, type Dispose, type GetPromise, type Getter, Once, race, Signal } from "@moq/signals"; import type * as Announce from "./announce.ts"; import * as announce from "./announced.ts"; +import type { Credential } from "./auth.ts"; import * as broadcast from "./broadcast.ts"; import { StreamCode, StreamError } from "./error.ts"; -import { Route, routesEqual } from "./hop.ts"; +import { type Cost, RouteInfo, routesEqual } from "./hop.ts"; import * as Instance from "./instance.ts"; import { compareRouteCandidates, @@ -43,7 +44,7 @@ import { wireOf, } from "./wire.ts"; -export type { Cost, Hop, Route } from "./hop.ts"; +export type { Cost, Hop, RouteInfo } from "./hop.ts"; export { HopSchema, isAnonymous } from "./hop.ts"; /** The rooted permissions shared by a handle and every route it inserts. */ @@ -243,10 +244,8 @@ class CoveringRoot { * A refusal is terminal, even while another source still serves: the slot ends, every handle * closes with the handler's error, and the slot leaves the table, so the next request asks * afresh. A refusal never falls through to a broader prefix or another advertiser. - * - * @internal */ -export interface RequestSlot { +interface RequestSlot { /** Open plain handles that can use a peer without discovery. */ blind: number; answer?: broadcast.Consumer; @@ -281,15 +280,13 @@ interface Resolution { * The preferred entry per prefix is the one requests resolve through. An originated * entry is forwarded by sessions; a received one is not, so a shared origin * cannot echo a peer's announcements back to it. - * - * @internal */ -export interface RouteEntry { +interface RouteEntry { readonly identity: object; readonly scope: Scope; /** The paths the entry may serve beneath its prefix, when its producer is scoped. */ readonly claim?: Path.Patterns; - readonly route: Signal; + readonly route: Signal; readonly originated: boolean; readonly server?: ServeState; } @@ -321,7 +318,7 @@ function preferredEntry( prefix: Path.Valid, entries: readonly RouteEntry[], skip?: (entry: RouteEntry) => boolean, - others: readonly Route[] = [], + others: readonly RouteInfo[] = [], ): RouteEntry | undefined { const eligible = entries.filter((entry) => !skip?.(entry)); // `others` compete at the prefix too, such as a broadcast announced here at the path. @@ -359,7 +356,7 @@ function unroutable(): StreamError { // A selected handler refused these requests; a coalesced route gap can have the same error. const refusedRequests = new WeakSet>(); -/** A served route from {@link Producer.requests}: the queue a handler drains. */ +/** A prefix route's queue of requests, from {@link Producer.routePrefix}: what a handler drains. */ class ServeState { readonly root: Path.Valid; /** The prefix the route claims; every served path is at or beneath it. */ @@ -531,7 +528,7 @@ class OriginState { // directions echo-free. created: Map | undefined = new Map(); local = new VersionedSignal | undefined>(new Map()); - advertisedLocal = new VersionedSignal | undefined>(new Map()); + advertisedLocal = new VersionedSignal | undefined>(new Map()); routes = new VersionedSignal | undefined>(new Map()); #snapshotVersion = ""; @@ -572,7 +569,7 @@ class OriginState { for (const [path, front] of this.local.peek() ?? []) { const local = { identity: front, - route: advertised?.get(path) ?? Route.default, + route: advertised?.get(path) ?? RouteInfo.default, exact: true, }; const list = out.get(path); @@ -591,6 +588,10 @@ class OriginState { // republish diffs as retract-then-announce and a re-price as another active. originated = new Signal(new Map()); + // Every open prefix route's server, advertised or not, so the origin's close ends each + // handler loop even for a route that is hidden or withdrawn. + servers = new Set(); + // Broadcasts materialized from a served route, keyed by exact path. Shared by every // request for the path so repeats reuse one accept; dropped (and closed) when the // providing route goes away or the last request releases it. @@ -1234,25 +1235,54 @@ export interface Reader { * @public */ export interface Table extends Reader { - /** Create an unannounced broadcast at `path`; see {@link Producer.createBroadcast}. */ - createBroadcast(path: Path.Valid): Publication; - - /** Advertise a prefix and serve requests under it; see {@link Producer.requests}. */ - requests(prefix: Path.Valid): Requests; - - /** Insert a route with protocol metadata. @internal */ - requestsRoute( - prefix: Path.Valid, - route?: - | Route - | { - instance?: Route["instance"]; - epoch?: Route["epoch"]; - hops?: Route["hops"]; - cost?: Route["cost"]; - auth?: Route["auth"]; - }, - ): Requests; + /** Create a route at exactly `path`, owning a new broadcast; see {@link Producer.route}. */ + route(path: Path.Valid, options?: RouteOptions): Route; + + /** Create a route over `prefix` that yields requests; see {@link Producer.routePrefix}. */ + routePrefix(prefix: Path.Valid, options?: RouteOptions): Route; +} + +/** + * How an application advertises a {@link Route}: its visibility at creation, its price, its + * credential, and, rarely, a stable instance. + * + * The default announces at once, at cost 0, under the session's scope, serving a fresh random + * instance minted when the route is created. + */ +export interface RouteOptions { + /** + * Create the route hidden: it exists for nobody until {@link Route.announce}. For a + * publisher that fills its catalog first, or answers a negotiation, before readers may find it. + */ + hidden?: boolean; + /** + * What pulling content via this route costs: lower wins among routes covering the same + * prefix and anonymity. A publisher prices content it already produces at zero, and content + * it would have to start producing on demand higher. + */ + cost?: Cost; + /** + * The credential the advertising request carries, from `auth.add()`. Only a session built + * on the handle that issued it presents it, as the token on its moq-transport + * PUBLISH_NAMESPACE; every other session advertises the route under its own scope. + */ + auth?: Credential; + /** + * Serve this stable instance in place of a freshly minted one. + * + * Only for a publisher that continues the instance's sequence space across restarts, + * announcing a higher {@link epoch} each time, such as a counter persisted on disk. Readers + * stitch every route of one instance together, so a publisher that restarts its group + * sequences under an old instance splices unrelated groups into their tracks. The highest + * epoch wins over every older one of the instance, cheaper or not. Naming an instance grants + * nothing: publishing still needs the path's grant. + * + * Do not start a named instance with `~`: that marks one a relay minted (see + * {@link Instance.isMinted}), which signing refuses to bind and a catalog's instance check skips. + */ + instance?: Instance.Valid; + /** Which incarnation of {@link instance} this is; raise it on each restart. Ignored without an instance. */ + epoch?: bigint; } /** Options for resolving one publisher instance with {@link Consumer.request}. */ @@ -1267,8 +1297,12 @@ export interface FollowOptions { instance?: Instance.Valid; } +// Route constructors, assigned in the classes' static blocks so neither class exposes one. +let makeRoute: (control: RouteControl) => Route; +let exactRoute: (producer: Producer, path: Path.Valid, options: RouteOptions, request: Request) => Route; + /** - * The write side of an origin: create broadcasts by path and advertise them. + * The write side of an origin: route broadcasts into it by path and advertise them. * * Independent of any connection. A connection given this origin (via its `publish` option) * announces and serves the table's originated advertisements for as long as the session @@ -1276,10 +1310,10 @@ export interface FollowOptions { * the origin down. A reconnecting session re-announces the table on each attach, so * advertisements made while offline surface on the next connection. * - * Create a broadcast, populate its tracks, then {@link Publication.announce}: an - * exact-path subscribe before the tracks exist is refused, and nobody can see or reach a - * broadcast until it announces. To publish broadcasts on demand instead, claim a prefix with - * {@link requests} and answer the requests beneath it. + * Create a {@link route} at a path and fill its broadcast; create it hidden and + * {@link Route.announce} it once its first tracks exist, since nobody can see or reach a hidden + * route. To publish broadcasts on demand instead, claim a prefix with {@link routePrefix} and + * answer the requests beneath it. * * @public */ @@ -1297,6 +1331,10 @@ export class Producer implements Table { // identity across reads. #reader = makeConsumer(this.#state, this.#scope); + static { + exactRoute = (producer, path, options, request) => producer.#exact(path, options, request); + } + constructor() { const thisProducer = this; registerWire(this, { @@ -1331,7 +1369,7 @@ export class Producer implements Table { return thisProducer.#requests; }, changed: () => this.#changed(), - blind: (slot) => this.#state.blind(slot), + blind: (slot) => this.#state.blind(slot as RequestSlot), answer: (path, front) => this.#answer(this.#scope.path(path), front), routes: (path) => wireOf(this.#reader).routes(path), }); @@ -1361,52 +1399,48 @@ export class Producer implements Table { } /** - * Create a broadcast at `path`, returning its publication handle. + * Create a route at exactly `path`, owning a new broadcast to fill. * - * The broadcast exists for nobody until {@link Publication.announce}: announce - * streams skip it and requests for its path find nothing, on this origin exactly as at - * a peer. Announce once its tracks exist; {@link Publication.unannounce} - * withdraws it from everyone again. + * This is how local content enters an origin. Fill the broadcast through + * {@link Route.broadcast}. The route serves a fresh random instance, minted here and kept + * for its lifetime, across {@link Route.withdraw} and {@link Route.announce}, since its + * sequences continue: a new route is a new stream that never splices into an old one. A + * publisher that continues one sequence space across restarts may name a stable instance + * instead ({@link RouteOptions.instance}). * - * Close the producer to drop it. Creating a path again supersedes the previous - * broadcast: the origin retracts and closes the old one, and tracks already subscribed - * keep serving until they end. The broadcast serves a fresh random {@link Route.instance}, - * kept across announce, unannounce and re-announce, so a restart is a new stream rather - * than a splice into the old one; at the same instance, a local broadcast competes on cost - * and wins ties. A publisher that continues one sequence space across restarts may name a - * stable instance instead. + * Announced at once unless created {@link RouteOptions.hidden | hidden}. A hidden route + * exists for nobody until {@link Route.announce}: announce streams skip it and a request + * for its path finds nothing, on this origin exactly as at a peer. Create it hidden when + * the tracks a subscriber needs first, such as a catalog, are not there yet. To serve paths + * on demand without publishing each one, use {@link routePrefix}. + * + * Closing the route retracts it and closes its broadcast, and so does closing the + * broadcast. Creating a path again supersedes the previous route: the origin retracts it + * and closes its broadcast, and tracks already subscribed keep serving until they end. At + * the same instance, a local broadcast competes on cost and wins ties. */ - createBroadcast(path: Path.Valid): Publication { + route(path: Path.Valid, options: RouteOptions = {}): Route { + return this.#exact(path, options); + } + + /** An exact route at `path`, answering `request` on its first announce when it is a job's. */ + #exact(path: Path.Valid, options: RouteOptions, request?: Request): Route { path = this.#scope.path(path); if (this.#borrowed?.closed) throw new Error("origin handle is closed"); publishPath(path); const created = this.#state.created; if (!created) throw new Error("origin is closed"); + // Normalized first, so a bad cost throws before anything is created. + let info = RouteInfo.normalize({ + instance: options.instance ?? Instance.random(), + epoch: options.instance === undefined ? 0n : options.epoch, + cost: options.cost, + auth: options.auth, + }); const producer = new broadcast.Producer(); hooks.stampPath(producer, path); const front = producer.consume(); - // The publication's own stream, kept across announce, unannounce and re-announce since - // its sequences continue. A route naming another instance replaces it. - let instance = Instance.random(); - let epoch = 0n; - - const announcer: broadcast.Announcer = { - announce: (route) => { - if (route.instance !== undefined) { - instance = route.instance; - epoch = route.epoch ?? 0n; - } - this.#advertiseExact(path, front, { ...route, instance, epoch }); - }, - unannounce: () => this.#retractExact(path, front), - route: () => - this.#state.local.peek()?.get(path) === front - ? this.#state.advertisedLocal.peek()?.get(path) - : undefined, - }; - hooks.attachAnnouncer(producer, announcer); - const entry = { producer, front }; const previous = created.get(path); created.set(path, entry); @@ -1415,20 +1449,71 @@ export class Producer implements Table { retire(previous); } - // Drop it when the broadcast closes, unless a recreate already replaced it: a stale - // broadcast closing must not unpublish the live one. Clearing `created` also stops a - // later announce. + // The request a job's route answers when it first announces. + let pending = request; + // Drop the route when its broadcast closes, unless a recreate already replaced it: a + // stale broadcast closing must not unpublish the live one. Clearing `created` also stops + // a later announce. A job's unanswered request can never be answered now. const release = this.#hold(() => { + stop(); this.#retractExact(path, front); - if (this.#state.created?.get(path) === entry) this.#state.created.delete(path); + if (created.get(path) === entry) created.delete(path); retire(entry); + const job = pending; + pending = undefined; + if (job) rejectJob(job, unroutable()); }); - void front.closed.then(release); + // Synchronous, so a request made right after the broadcast closes finds it gone. + const stop = hooks.onClosed(producer, release); + + const announced = () => this.#state.local.peek()?.get(path) === front; + const announce = () => { + if (producer.closed.peek() !== undefined) throw new Error("broadcast is closed"); + const job = pending; + if (!job) { + this.#advertiseExact(path, front, info); + return; + } + pending = undefined; + try { + // A request released meanwhile can never be answered, so this route never announces. + if (!jobPending(job)) throw unroutable(); + this.#advertiseExact(path, front, info); + } catch (err) { + release(); + rejectJob(job, err instanceof Error ? err : new Error(String(err))); + throw err; + } + answerJob(job); + }; + const change = (next: RouteInfo) => { + if (producer.closed.peek() !== undefined) throw new Error("broadcast is closed"); + if (!this.#state.created) throw new Error("origin is closed"); + info = next; + if (announced()) this.#advertiseExact(path, front, info); + }; - return makePublication(producer, announcer); + const route = makeRoute({ + broadcast: producer, + instance: () => info.instance as Instance.Valid, + announce, + withdraw: () => this.#retractExact(path, front), + announced, + change: (update) => change(RouteInfo.normalize({ ...info, ...update })), + requested: async function* () {}, + close: release, + info: () => (announced() ? this.#state.advertisedLocal.peek()?.get(path) : undefined), + update: (next) => { + const named = RouteInfo.normalize(next); + info = named.instance === undefined ? { ...named, instance: info.instance, epoch: info.epoch } : named; + announce(); + }, + }); + if (!options.hidden) announce(); + return route; } - #advertiseExact(path: Path.Valid, front: broadcast.Consumer, route: Route): void { + #advertiseExact(path: Path.Valid, front: broadcast.Consumer, route: RouteInfo): void { if (!this.#state.local.peek()) throw new Error("origin is closed"); if (this.#state.created?.get(path)?.front !== front) throw new Error("broadcast is closed"); // Both maps move together, so every reader sees the broadcast and its route at once. @@ -1455,60 +1540,39 @@ export class Producer implements Table { } /** - * Advertise `prefix` and serve the requests beneath it. + * Create a route over `prefix` that yields the requests beneath it. * - * A route is always a prefix: it claims `prefix` and every path beneath it (the - * empty prefix claims every path). A service that only serves some of them - * advertises the covering prefix and rejects the rest as they are requested; - * consumers narrow with a {@link Path.Pattern} locally. The advertisement is - * visible to {@link Consumer.announced} and forwarded by sessions for as long as - * the returned {@link Requests} lives. A consumer resolving a path under it that - * no announced local broadcast wins is handed to the handle as a {@link Request}. + * A route is always a prefix: it claims `prefix` and every path beneath it (the empty + * prefix claims every path). A service that only serves some of them advertises the + * covering prefix and rejects the rest as they are requested; consumers narrow with a + * {@link Path.Pattern} locally. The route is priced, credentialed and shown like an exact + * one, and forwarded by sessions while it is visible. + * + * A consumer resolving a path under it that no announced local broadcast wins is handed to + * {@link Route.requested} as a {@link Request}: answer it by serving a broadcast already held + * ({@link Request.serve}), under this route's instance, or by creating the path's own exact + * route ({@link Request.route}), under a fresh instance, so restarting one job never splices + * into a copy of the last. A publisher that knows its broadcasts creates each one's exact + * {@link route} instead, so subscribers can enumerate them. */ - requests(prefix: Path.Valid): Requests { - return this.#insertRoute(prefix, Route.default, true, true); - } - - /** Insert an originated claim with route metadata that answers through `Request.serve`, for tests and benches. @internal */ - requestsRoute( - prefix: Path.Valid, - route: - | Route - | { - instance?: Route["instance"]; - epoch?: Route["epoch"]; - hops?: Route["hops"]; - cost?: Route["cost"]; - auth?: Route["auth"]; - } = Route.default, - ): Requests { - return this.#insertRoute(prefix, Route.normalize(route), true, false); + routePrefix(prefix: Path.Valid, options: RouteOptions = {}): Route { + const info = RouteInfo.normalize({ + instance: options.instance, + epoch: options.epoch, + cost: options.cost, + auth: options.auth, + }); + return this.#serving(prefix, info, true, true, !options.hidden); } - /** - * Land a route a peer announced, served through the returned handle. Same as - * {@link requests} but not originated, so a session never announces it back. - * - * @internal - */ - #receive( - prefix: Path.Valid, - route: - | Route - | { - instance?: Route["instance"]; - epoch?: Route["epoch"]; - hops?: Route["hops"]; - cost?: Route["cost"]; - auth?: Route["auth"]; - } = Route.default, - ): Requests { - return this.#insertRoute(prefix, Route.normalize(route), false, false); - } - - #insertRoute(prefix: Path.Valid, route: Route, originated: boolean, publishes: boolean): Requests { + /** Land a route a peer announced, taken as given. Not originated, so a session never announces it back. */ + #receive(prefix: Path.Valid, route?: Partial): Route { + return this.#serving(prefix, RouteInfo.normalize(route), false, false, true); + } + + #serving(prefix: Path.Valid, route: RouteInfo, originated: boolean, publishes: boolean, visible: boolean): Route { prefix = this.#scope.prefix(prefix); - // A handle that names no instance serves one of its own. + // A route that names no instance serves one of its own. if (route.instance === undefined) route = { ...route, instance: Instance.random(), epoch: 0n }; publishPath(prefix); const server = new ServeState(this.#scope.root, prefix); @@ -1523,40 +1587,98 @@ export class Producer implements Table { }; server.onReject = (path, err) => this.#state.refuse(path, entry, err); - let closed = this.#borrowed?.closed ?? false; - if (!closed) { + let inserted = false; + let ended = false; + // Closing the origin drops the whole table without visiting each route, so a route + // still marked inserted learns of it here, matching an exact route's "origin is closed". + const open = () => { + if (ended) throw new Error("route is closed"); + if (this.#state.routes.peek()) return; + inserted = false; + throw new Error("origin is closed"); + }; + const insert = () => { + open(); + if (inserted) return; this.#state.routes.mutate((routes) => { - if (!routes) { - closed = true; - return; - } - const entries = routes.get(prefix); + const entries = routes?.get(prefix); if (entries) entries.unshift(entry); - else routes.set(prefix, [entry]); + else routes?.set(prefix, [entry]); }); - } - if (closed) { + inserted = true; + this.#state.rebuildOriginated(); + this.#state.refreshPrefix(prefix); + }; + // Take the entry out of the table, then end (or renew) the server before the requests + // beneath it reroute, so none of them resolves through an answer it already gave. + const remove = (server: () => void) => { + if (inserted) { + inserted = false; + this.#state.routes.mutate((routes) => { + const entries = routes?.get(prefix); + if (!entries) return; + const index = entries.indexOf(entry); + if (index < 0) return; + entries.splice(index, 1); + if (entries.length === 0) routes?.delete(prefix); + }); + } + server(); + this.#state.rebuildOriginated(); + this.#state.refreshPrefix(prefix); + }; + const release = this.#hold(() => { + ended = true; + this.#state.servers.delete(server); + remove(() => server.close()); + }); + // A route made after its origin (or this handle) closed is born retracted. + if (this.#borrowed?.closed || !this.#state.routes.peek()) { + ended = true; server.close(); - return makeDynamic(prefix, entry, this.#state, () => {}, publishes ? this : undefined); + } else { + this.#state.servers.add(server); + if (visible) insert(); } - this.#state.rebuildOriginated(); - this.#state.refreshPrefix(prefix); - const retract = this.#hold(() => { - this.#state.routes.mutate((routes) => { - const entries = routes?.get(prefix); - if (!entries) return; - const index = entries.indexOf(entry); - if (index < 0) return; - entries.splice(index, 1); - if (entries.length === 0) routes?.delete(prefix); - }); - server.close(); + const update = (next: RouteInfo) => { + open(); + const previous = entry.route.peek().instance; + const restart = inserted && previous !== next.instance; + if (restart) this.#state.restart(entry); + entry.route.set(next); + if (previous !== next.instance) server.reset(); + if (!inserted) return; this.#state.rebuildOriginated(); this.#state.refreshPrefix(prefix); - }); + this.#state.routes.mutate(() => {}); + }; - return makeDynamic(prefix, entry, this.#state, retract, publishes ? this : undefined); + const publisher = publishes ? this : undefined; + return makeRoute({ + instance: () => entry.route.peek().instance as Instance.Valid, + announce: insert, + withdraw: () => { + if (ended || !inserted) return; + remove(() => server.reset()); + }, + announced: () => inserted && this.#state.routes.peek() !== undefined, + change: (changed) => update(RouteInfo.normalize({ ...entry.route.peek(), ...changed })), + requested: () => serveRequests(server, publisher), + close: release, + info: () => (inserted && this.#state.routes.peek() ? entry.route.peek() : undefined), + update: (next) => { + // A route naming no instance keeps the one it serves. + const named = RouteInfo.normalize(next); + const current = entry.route.peek(); + update( + named.instance === undefined + ? { ...named, instance: current.instance, epoch: current.epoch } + : named, + ); + insert(); + }, + }); } /** @@ -1698,16 +1820,22 @@ export class Producer implements Table { if (this.#state.closed.peek() !== undefined) return; this.#state.closed.set(abort ?? null); for (const watch of this.#state.watchers.values()) watch.version.update((n) => n + 1); - for (const created of this.#state.created?.values() ?? []) retire(created); + // Cleared before the broadcasts close, so each route's synchronous retraction finds + // nothing left to rebuild rather than rebuilding the table once per route. + const created = this.#state.created; this.#state.created = undefined; this.#state.local.update(() => undefined); this.#state.advertisedLocal.update(() => undefined); + for (const entry of created?.values() ?? []) retire(entry); this.#state.routes.update((routes) => { for (const entries of routes?.values() ?? []) { for (const entry of entries) entry.server?.close(abort); } return undefined; }); + // A hidden or withdrawn prefix route is out of the table but its handler still waits. + for (const server of this.#state.servers) server.close(abort); + this.#state.servers.clear(); this.#state.originated.update(() => undefined); // Materialized broadcasts are handles we opened; release them. for (const cached of this.#state.materialized.values()) { @@ -1752,20 +1880,12 @@ let makeFollowing: ( dispose: Dispose, ) => Following; -let makeDynamic: ( - prefix: Path.Valid, - entry: RouteEntry, - state: OriginState, - retract: Dispose, - publisher?: Producer, -) => Requests; - let makeRequest: (path: Path.Valid, server: ServeState) => Request; let finishRequest: (request: Request, err: Error) => void; let setRequestPublisher: (request: Request, publisher: Producer | undefined) => void; -let makePrepared: (request: Request, publication: Publication) => Prepared; -let publishPrepared: (request: Request, publication: Publication) => Publication; -let rejectPrepared: (request: Request, err: Error) => void; +let jobPending: (request: Request) => boolean; +let answerJob: (request: Request) => void; +let rejectJob: (request: Request, err: Error) => void; /** * An owned request for one publisher instance at a broadcast path; see {@link Consumer.request}. @@ -2393,21 +2513,6 @@ export class Consumer implements Reader { producer.close(); } - /** - * The local table, borrowed by the wire publishers to answer subscribes. - * - * Deliberately excludes received routes: a session never re-announces what a peer - * told it, so an origin wired to both directions of a connection cannot echo. - * Borrowed, not owned: do not close the fronts. Undefined once the origin closes. - * - * @internal - */ - /** - * Originated advertisements a session should forward: exact-path announces plus - * originated dynamics. Undefined once the origin closes. - * - * @internal - */ /** * The announced local broadcast at `path`, when it beats the originated routes there. * Resolves through what rebuildOriginated advertised: a peer never sees received routes. @@ -2510,140 +2615,172 @@ export class Consumer implements Reader { } } +/** What one {@link Route} does, exact or prefix. */ +interface RouteControl { + readonly broadcast?: broadcast.Producer; + instance(): Instance.Valid; + announce(): void; + withdraw(): void; + announced(): boolean; + change(update: Partial>): void; + requested(): AsyncIterableIterator; + close(): void; + info(): RouteInfo | undefined; + update(info: Partial): void; +} + +/** The requests arriving on a prefix route's `server`, each answerable with a route of `publisher`'s when it has one. */ +async function* serveRequests(server: ServeState, publisher: Producer | undefined): AsyncIterableIterator { + let current: Request | undefined; + const drop = () => { + current?.reject(unroutable()); + current = undefined; + }; + // Keep the cursor while draining: restarting it would rescan deleted entries. + let queued = server.queue.peek().values(); + try { + for (;;) { + const next = queued.next(); + if (!next.done) { + drop(); + server.queue.mutate((queue) => { + queue.delete(next.value); + }); + current = next.value; + setRequestPublisher(current, publisher); + yield next.value; + continue; + } + if (server.closed.peek() !== undefined) return; + await Signal.race(server.queue, server.closed); + queued = server.queue.peek().values(); + } + } finally { + drop(); + } +} + /** - * A served route from {@link Producer.requests}: advertises a prefix and answers the + * A route in an origin: an exact one owning its broadcast, or a prefix one answering the * requests beneath it. * - * Drop it (or {@link close}) to retract the route and reject anything still waiting - * with {@link StreamCode | StreamCode.Unroutable}. Close it and claim again to change it. + * Create an exact route with {@link Producer.route}, a prefix route with + * {@link Producer.routePrefix}, or a job's exact route with {@link Request.route}. + * + * ```ts + * // Fill the catalog before readers can find it. + * const route = origin.route(Path.from("live/alice"), { hidden: true }); + * route.broadcast.createTrack("catalog.json"); + * route.announce(); // visible now, same instance + * route.setCost(5n); // re-prices in place + * route.withdraw(); // hidden; announce() again continues the same stream + * ``` + * + * {@link close} retracts it and closes its broadcast, and so does closing the broadcast. * * @public */ -export class Requests { - /** The prefix this handle advertises. */ - readonly prefix: Path.Valid; - - #entry: RouteEntry; - #state: OriginState; - #retract: Dispose; - #publisher?: Producer; - #closed = false; +export class Route { + readonly #control: RouteControl; - private constructor( - prefix: Path.Valid, - entry: RouteEntry, - state: OriginState, - retract: Dispose, - publisher?: Producer, - ) { - this.prefix = Path.stripPrefix(entry.scope.root, prefix) ?? Path.empty(); - this.#entry = entry; - this.#state = state; - this.#retract = retract; - this.#publisher = publisher; + private constructor(control: RouteControl) { + this.#control = control; + registerWire(this, { + get info() { + return control.info(); + }, + update: (info) => control.update(info), + }); } static { - makeDynamic = (prefix, entry, state, retract, publisher) => - new Requests(prefix, entry, state, retract, publisher); + makeRoute = (control) => new Route(control); + } + + /** The broadcast this exact route owns, to fill with tracks. Throws on a prefix route, which owns none. */ + get broadcast(): broadcast.Producer { + const producer = this.#control.broadcast; + if (!producer) throw new Error("a prefix route owns no broadcast; answer its requests"); + return producer; } - /** The route this handle advertises. */ - get route(): Route { - return this.#entry.route.peek(); + /** The stream this route serves, minted when it was created unless {@link RouteOptions.instance} named one. */ + get instance(): Instance.Valid { + return this.#control.instance(); } /** - * Replace the route in place. The prefix is fixed at announce time. - * - * A route naming no instance keeps the one this handle serves. At the same instance this - * re-prices (or, at a higher epoch, continues the stream): consumers see an update and every - * handle survives. Another instance names another stream: - * consumers see a restart, resolved requests keep their old broadcast until closed, and a - * re-request never joins it. Requests still waiting on this handle carry over: the handler - * is asked again under the new instance, and its answer to a request asked before the change - * is dropped, never served under the new instance. A new or unresolved request pinned to the - * old instance is refused as unroutable. The answers already served are forgotten, so the next - * request for one of those paths asks the handler again too. The broadcasts it served keep - * running for the subscriptions already on them; close them to end those too. - * Route selection still applies across instances. To re-price, start from the current route, `updateRoute({ ...dynamic.route, cost })`. + * Make the route visible, or keep it so. Idempotent. * - * @internal + * Visible to local consumers before it returns. A job's route ({@link Request.route}) also + * answers the requesters waiting on its path. Throws once the route or its broadcast closed, + * and, announcing nothing, with {@link StreamCode | StreamCode.Unroutable} when a job's request + * was released or its prefix route retracted meanwhile: that route can never announce. */ - updateRoute( - route: - | Route - | { - instance?: Route["instance"]; - epoch?: Route["epoch"]; - hops?: Route["hops"]; - cost?: Route["cost"]; - auth?: Route["auth"]; - }, - ): void { - if (this.#closed) throw new Error("dynamic is closed"); - const current = this.#entry.route.peek(); - const named = Route.normalize(route); - // A route naming no instance keeps the one this handle serves. - const next = - named.instance === undefined ? { ...named, instance: current.instance, epoch: current.epoch } : named; - const previous = current.instance; - if (previous !== next.instance) this.#state.restart(this.#entry); - this.#entry.route.set(next); - if (previous !== next.instance) this.#entry.server?.reset(); - this.#state.rebuildOriginated(); - this.#state.refreshPrefix(Path.join(this.#entry.scope.root, this.prefix)); - this.#state.routes.mutate(() => {}); + announce(): void { + this.#control.announce(); + } + + /** + * Hide the route from everyone, local and remote alike, keeping its broadcast and instance: + * {@link announce} brings the same stream back. Requests for the path fail with + * {@link StreamCode | StreamCode.Unroutable} meanwhile, while tracks already in flight carry + * on to their own end. Idempotent. + */ + withdraw(): void { + this.#control.withdraw(); } - /** Retract the route and reject anything still waiting. Idempotent. */ + /** Whether the route is visible. */ + get announced(): boolean { + return this.#control.announced(); + } + + /** + * Re-price the route: lower wins among routes covering the same prefix and anonymity. A + * visible route changes in place, as an update to its readers; a hidden one announces at + * this price. Throws once the route or its broadcast closed. + */ + setCost(cost: Cost): void { + this.#control.change({ cost }); + } + + /** + * Swap the credential the advertising request carries; see {@link RouteOptions.auth}. + * Undefined advertises under the session's scope. Throws once the route or its broadcast closed. + */ + setAuth(auth?: Credential): void { + this.#control.change({ auth }); + } + + /** + * The requests beneath this prefix route, as they arrive, each to answer with + * {@link Request.serve}, {@link Request.route} or {@link Request.reject}. Advancing the + * iterator or closing it without answering rejects the request. Ends once the route is + * closed or the origin closes, and at once on an exact route, which yields no requests. + */ + requested(): AsyncIterableIterator { + return this.#control.requested(); + } + + /** Retract the route for good, closing its broadcast and rejecting anything still waiting. Idempotent. */ close(): void { - if (this.#closed) return; - this.#closed = true; - this.#retract(); - } - - /** Requests under this prefix, as they arrive, each to {@link Request.prepare} or reject. */ - async *requested(): AsyncIterableIterator { - const server = this.#entry.server; - if (!server) return; - let current: Request | undefined; - const drop = () => { - current?.reject(unroutable()); - current = undefined; - }; - // Keep the cursor while draining: restarting it would rescan deleted entries. - let queued = server.queue.peek().values(); - try { - for (;;) { - const next = queued.next(); - if (!next.done) { - drop(); - server.queue.mutate((queue) => { - queue.delete(next.value); - }); - current = next.value; - setRequestPublisher(current, this.#publisher); - yield next.value; - continue; - } - if (server.closed.peek() !== undefined) return; - await Signal.race(server.queue, server.closed); - queued = server.queue.peek().values(); - } - } finally { - drop(); - } + this.#control.close(); + } + + /** Calls {@link close}, so `using` retracts the route. */ + [Symbol.dispose](): void { + this.close(); } } /** * A pending request for a broadcast to be served on demand. * - * Yielded by {@link Requests.requested}. {@link prepare} then {@link Prepared.publish} - * resolves it with a new exact-path broadcast; {@link serve} answers with a held broadcast; - * {@link reject} resolves it with an error. - * Advancing the iterator or closing it without answering rejects the request. + * Yielded by {@link Route.requested}. Answer it one of three ways: {@link serve} a broadcast + * already held, under the prefix route's instance; create the path's own exact route with + * {@link route}, under a fresh instance; or {@link reject} it with an error. Advancing the + * iterator or closing it without answering rejects the request. * * @public */ @@ -2666,16 +2803,14 @@ export class Request { setRequestPublisher = (request, publisher) => { request.#publisher = publisher; }; - publishPrepared = (request, publication) => { - if (!request.#server.has(request)) throw new Error("request is closed"); - publication.announce(); + jobPending = (request) => request.#server.has(request); + answerJob = (request) => { // Its exact route owns availability: never cache a published job under the // prefix, which would keep serving it after that exact route is withdrawn. request.#server.forget(Path.join(request.#server.root, request.path), request); request.#server.settled.update((n) => n + 1); - return publication; }; - rejectPrepared = (request, err) => request.#server.reject(request, err); + rejectJob = (request, err) => request.#server.reject(request, err); finishRequest = (request, err) => { request.#done = true; request.#withdrawn = true; @@ -2683,15 +2818,26 @@ export class Request { }; } - /** Start answering as a new stream under a fresh instance, hidden until published. */ - prepare(): Prepared { + /** + * Answer with the path's own exact route, owning a new broadcast. + * + * The route serves a fresh instance unless `options` names one, so a job that ends and + * restarts beneath the same prefix is a new stream for its restarted sequences. Closing the + * route withdraws only this path: the prefix route keeps answering later requests. Created + * visible, the route announces now and answers the requesters waiting on its path. Created + * {@link RouteOptions.hidden | hidden}, they wait until {@link Route.announce}, so the job can + * fill its catalog first; closing the route or its broadcast before then refuses them. + * + * Throws {@link StreamCode | StreamCode.Unroutable} on a request a session forwarded, which can + * only {@link serve} its peer's broadcast, and, announcing nothing, once the request was + * released or its prefix route retracted. Otherwise it throws as {@link Producer.route} does. + */ + route(options: RouteOptions = {}): Route { if (this.#done) throw new Error("request is closed"); - if (!this.#publisher) throw new Error("forwarded requests cannot be prepared"); - const publication = this.#publisher.createBroadcast(this.path); - // Only the fill handle escapes until publish, so the answer cannot announce itself - // under another instance or skip the request's admission. + if (!this.#publisher) throw unroutable(); + const route = exactRoute(this.#publisher, this.path, options, this); this.#done = true; - return makePrepared(this, publication); + return route; } /** @@ -2699,8 +2845,8 @@ export class Request { * * Takes ownership of a consumer; a producer stays the caller's. Every answer at this * path belongs to the prefix route's instance and must continue the same sequences and - * bytes. Start a new prefix route for different content, or use {@link prepare} and - * {@link Prepared.publish} for a job that can restart independently. + * bytes. Start a new prefix route for different content, or use {@link route} for a job + * that can restart independently. */ serve(source: broadcast.Producer | broadcast.Consumer): void { if (this.#done) { @@ -2721,107 +2867,3 @@ export class Request { this.#server.reject(this, err); } } - -let makePublication: (producer: broadcast.Producer, announcer: broadcast.Announcer) => Publication; - -/** An origin-owned broadcast and the capability to announce its route. */ -export class Publication { - /** The broadcast to fill with tracks before announcing it. */ - readonly broadcast: broadcast.Producer; - readonly #announcer: broadcast.Announcer; - - private constructor(producer: broadcast.Producer, announcer: broadcast.Announcer) { - this.broadcast = producer; - this.#announcer = announcer; - } - - static { - makePublication = (producer, announcer) => new Publication(producer, announcer); - } - - /** The route this broadcast is announced with, if any. */ - get route(): Route | undefined { - return this.#announcer.route(); - } - - /** - * Announce this broadcast, or replace its route; retain its instance when changing only cost. - * Announce once its initial tracks exist. Throws after the broadcast closes or is replaced. - */ - announce( - route: - | Route - | { - instance?: Route["instance"]; - epoch?: Route["epoch"]; - hops?: Route["hops"]; - cost?: Route["cost"]; - auth?: Route["auth"]; - } = Route.default, - ): void { - if (this.broadcast.closed.peek() !== undefined) throw new Error("broadcast is closed"); - this.#announcer.announce(Route.normalize(route)); - } - - /** Retract this broadcast's route until announced again, without closing its fill handle. */ - unannounce(): void { - this.#announcer.unannounce(); - } -} - -/** - * A claim answer being filled before its exact route is announced. - * - * Use `using` or {@link close} to refuse it unless {@link publish} transfers its broadcast. - * Closing the unpublished broadcast also refuses the request. A retained, unclosed answer - * keeps the request pending; garbage collection provides no prompt cleanup guarantee. - */ -export class Prepared { - /** The unannounced broadcast to fill before publishing; only {@link publish} announces it. */ - readonly broadcast: broadcast.Producer; - readonly #request: Request; - readonly #publication: Publication; - readonly #stop: Dispose; - #done = false; - - private constructor(request: Request, publication: Publication) { - this.#request = request; - this.broadcast = publication.broadcast; - this.#publication = publication; - // Synchronous, so a request made right after the broadcast closes reaches the claim again. - this.#stop = hooks.onClosed(this.broadcast, () => this.close()); - } - - static { - makePrepared = (request, publication) => new Prepared(request, publication); - } - - /** Announce the filled broadcast and resolve every waiting requester, refusing them if it cannot be announced. */ - publish(): Publication { - // Closing the broadcast closes this answer at once, so `#done` covers it too. - if (this.#done) throw new Error("prepared answer is closed"); - this.#done = true; - this.#stop(); - try { - return publishPrepared(this.#request, this.#publication); - } catch (err) { - this.broadcast.close(); - rejectPrepared(this.#request, err instanceof Error ? err : new Error(String(err))); - throw err; - } - } - - /** Refuse an unpublished answer as unroutable and close its broadcast. Idempotent. */ - close(): void { - if (this.#done) return; - this.#done = true; - this.#stop(); - this.broadcast.close(); - rejectPrepared(this.#request, unroutable()); - } - - /** Calls {@link close}, so `using` refuses an unpublished answer. */ - [Symbol.dispose](): void { - this.close(); - } -} diff --git a/js/net/src/parked-expiry.test.ts b/js/net/src/parked-expiry.test.ts index 4b302a86f30..624901a6005 100644 --- a/js/net/src/parked-expiry.test.ts +++ b/js/net/src/parked-expiry.test.ts @@ -30,9 +30,8 @@ for (const protocol of protocols) { const installed = clock.install(); const pair = createMockTransportPair(protocol.alpn); const origin = new Origin(); - const broadcastPublication = origin.createBroadcast(Path.from("parked")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("parked")); + const broadcast = broadcastRoute.broadcast; // No publisher limit, so the cache eviction rather than a stale verdict ends a long budget. const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const write = (sequence: bigint) => { @@ -152,9 +151,8 @@ for (const protocol of protocols) { const installed = clock.install(); const pair = createMockTransportPair(protocol.alpn); const origin = new Origin(); - const broadcastPublication = origin.createBroadcast(Path.from("parked")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("parked")); + const broadcast = broadcastRoute.broadcast; const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const write = (sequence: bigint, frames: number) => { const group = track.createGroup(sequence); diff --git a/js/net/src/resume.model.test.ts b/js/net/src/resume.model.test.ts index 919dee85a19..cf06c9f77fc 100644 --- a/js/net/src/resume.model.test.ts +++ b/js/net/src/resume.model.test.ts @@ -17,7 +17,7 @@ import fc from "fast-check"; import { Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "./broadcast.ts"; import { NotFound, StreamCode, StreamError, TooFarBehind } from "./error.ts"; import type { Frame, Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; -import { HopSchema, Route } from "./hop.ts"; +import { HopSchema, RouteInfo } from "./hop.ts"; import * as Instance from "./instance.ts"; import { hooks } from "./internal.ts"; import { type Consumer as OriginConsumer, Producer as OriginProducer, type Requesting } from "./origin.ts"; @@ -447,7 +447,7 @@ class Model { up(instance: number, slot: number): void { const publisher = this.instances[instance]; if (publisher.routes[slot]) return; - const route = Route.normalize({ + const route = RouteInfo.normalize({ instance: INSTANCES[instance], hops: [HopSchema.parse(BigInt(10 * (instance + 1) + slot))], // The second instance's routes all undercut the first's. diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 34dbb1c308a..69b340e5aad 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -3,7 +3,7 @@ import { Manual, Milli, Nano, yieldNow } from "@moq/clock"; import { Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "./broadcast.ts"; import { NotFound, SessionCode, SessionError, StreamCode, StreamError } from "./error.ts"; import { type Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; -import { Route } from "./hop.ts"; +import { RouteInfo } from "./hop.ts"; import type { Session as IetfSession } from "./ietf/session.ts"; import { Subscriber as IetfSubscriber } from "./ietf/subscriber.ts"; import { Version as IetfVersion } from "./ietf/version.ts"; @@ -39,7 +39,7 @@ async function isPending(promise: Promise): Promise { /** A stand-in session announcing `path` under the shared instance at `cost`, serving `source`. */ function serve(origin: Producer, source: BroadcastProducer, cost: bigint) { - const handle = wireOf(origin).receive(path, Route.normalize({ instance: INSTANCE, cost })); + const handle = wireOf(origin).receive(path, RouteInfo.normalize({ instance: INSTANCE, cost })); void (async () => { for await (const request of handle.requested()) request.serve(source.consume()); })(); @@ -485,9 +485,8 @@ test("a resumed fork shares an on-demand track request", async () => { test("a lagging same-instance replica resumes from one publisher's bytes exactly once", async () => { const { clock, installed } = manual(); const publisher = new Producer(); - const originalPublication = publisher.createBroadcast(path); - const original = originalPublication.broadcast; - originalPublication.announce({ instance: INSTANCE }); + const originalRoute = publisher.route(path, { instance: INSTANCE }); + const original = originalRoute.broadcast; const source = original.createTrack("seq", { maxAge: null }); const origin = new Producer(); @@ -943,7 +942,7 @@ test("between routes a reader keeps reading the copy it has", async () => { expect(drain(sub)).toEqual([0n]); // The next route has not answered when the old one is retracted. - const next = wireOf(origin).receive(path, Route.normalize({ instance: INSTANCE, cost: 1n })); + const next = wireOf(origin).receive(path, RouteInfo.normalize({ instance: INSTANCE, cost: 1n })); const asked = next.requested(); disposeA(); await settle(); @@ -1832,7 +1831,7 @@ test("a fetched group that fails on the route still serving waits for the next r const b = new BroadcastProducer(); const ta = copy(a); const tb = copy(b); - // Route a's request handler holds the refetch of its failed group open, as Rust's tests do + // RouteInfo a's request handler holds the refetch of its failed group open, as Rust's tests do // with `requests()`: without one, a miss there is NotFound at once. const pending = ta.producer.requests(); const failing = ta.write(5n, 1, false); @@ -1864,7 +1863,7 @@ test("a group handed out already failed with its route still continues on the ne const b = new BroadcastProducer(); const ta = copy(a); const tb = copy(b); - // Route a's request handler holds the refetch of its failed group open until the next route. + // RouteInfo a's request handler holds the refetch of its failed group open until the next route. const pending = ta.producer.requests(); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); diff --git a/js/net/src/retention.test.ts b/js/net/src/retention.test.ts index 029176110d3..81d5d6d4f4b 100644 --- a/js/net/src/retention.test.ts +++ b/js/net/src/retention.test.ts @@ -81,9 +81,8 @@ async function session(alpn: string) { accept({ transport: pair.server, url, publish: origin.consume() }), ]); - const broadcastPublication = origin.createBroadcast(Path.from("test")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("test")); + const broadcast = broadcastRoute.broadcast; const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const remote = wireOf(client).consume(Path.from("test")); diff --git a/js/net/src/subscribe_priority.test.ts b/js/net/src/subscribe_priority.test.ts index 1ccae6bdb62..caa93dff11f 100644 --- a/js/net/src/subscribe_priority.test.ts +++ b/js/net/src/subscribe_priority.test.ts @@ -60,9 +60,8 @@ test.each([Lite.ALPN_07_WIP, ...Object.values(Ietf.ALPN)])( "%s follows the aggregate priority upstream", async (protocol) => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const [client, server] = await session(protocol, origin); @@ -100,9 +99,8 @@ test.each(Object.values(Ietf.ALPN))("%s ends a subscription mid-update without a await yieldNow(); }); const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const [client, server] = await session(protocol, origin); let closed: Error | null | undefined; @@ -137,9 +135,8 @@ test.each(Object.values(Ietf.ALPN))("%s ends a subscription mid-update without a // update of defaults first, as on lite and in Rust. test.each(Object.values(Ietf.ALPN))("%s sends no update when the last subscriber leaves", async (protocol) => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const [client, server] = await session(protocol, origin); try { @@ -164,9 +161,8 @@ test.each(Object.values(Ietf.ALPN))("%s sends no update when the last subscriber // track with the error rather than leaving it at a stale priority. Nothing reaches the wire. test.each(Object.values(Ietf.ALPN))("%s ends the track when an update fails to encode", async (protocol) => { const origin = new OriginProducer(); - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(path); + const broadcast = broadcastRoute.broadcast; const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const [client, server] = await session(protocol, origin); let closed: Error | null | undefined; diff --git a/js/net/src/tail.test.ts b/js/net/src/tail.test.ts index 40a81d606c1..b354df703ae 100644 --- a/js/net/src/tail.test.ts +++ b/js/net/src/tail.test.ts @@ -26,9 +26,8 @@ async function session(protocol: string) { connect({ url, transport: pair.client }), accept({ transport: pair.server, url, publish: origin.consume() }), ]); - const broadcastPublication = origin.createBroadcast(Path.from("test")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("test")); + const broadcast = broadcastRoute.broadcast; const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const remote = wireOf(client).consume(Path.from("test")); const reader = remote diff --git a/js/net/src/terminal.test.ts b/js/net/src/terminal.test.ts index 796ae45243d..009cfc2a9b6 100644 --- a/js/net/src/terminal.test.ts +++ b/js/net/src/terminal.test.ts @@ -57,8 +57,7 @@ test("an unanswered track request is refused with the dropped producer's error", test("a lite protocol violation reaches the subscribed track and its open group", async () => { const pair = createMockTransportPair(ALPN_06); const origin = new OriginProducer(); - const publication = origin.createBroadcast(Path.from("room")); - publication.announce(); + const publication = origin.route(Path.from("room")); const producer = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI }); producer.appendGroup().writeFrame(textFrame("prefix")); const url = new URL("https://example.com"); diff --git a/js/net/src/untimed.test.ts b/js/net/src/untimed.test.ts index 2ce19df361d..eae4fe355e2 100644 --- a/js/net/src/untimed.test.ts +++ b/js/net/src/untimed.test.ts @@ -44,9 +44,8 @@ async function roundTrip(wire: Wire, timescale: Timescale | undefined, timestamp accept({ transport: pair.server, url, version: wire.version, publish: origin.consume() }), ]); - const broadcastPublication = origin.createBroadcast(Path.from("test")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = origin.route(Path.from("test")); + const broadcast = broadcastRoute.broadcast; // Every request is answered, including the TRACK lookup lite-05+ makes before subscribing. const serving = (async () => { for (;;) { @@ -115,9 +114,8 @@ test("a forwarded untimed track stays untimed", async () => { connect({ url, transport: downstream.client }), ]); - const broadcastPublication = source.createBroadcast(Path.from("test")); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); + const broadcastRoute = source.route(Path.from("test")); + const broadcast = broadcastRoute.broadcast; const serving = (async () => { for (;;) { const request = await wireOf(broadcast).requested(); @@ -130,7 +128,7 @@ test("a forwarded untimed track stays untimed", async () => { // Serve the downstream session from the upstream one through a copy the forwarding // node produces. - const dynamic = relay.requestsRoute(Path.from("test")); + const dynamic = relay.routePrefix(Path.from("test")); const inputs: BroadcastConsumer[] = []; const forwarding = (async () => { for await (const request of dynamic.requested()) { diff --git a/js/net/src/wire.ts b/js/net/src/wire.ts index d8a7e59e99c..c39b99474b1 100644 --- a/js/net/src/wire.ts +++ b/js/net/src/wire.ts @@ -11,7 +11,7 @@ import type { Dispose, GetPromise, Getter } from "@moq/signals"; import type * as broadcast from "./broadcast.ts"; import type * as datagram from "./datagram.ts"; import type { Consumer as GroupConsumer } from "./group.ts"; -import type { Route } from "./hop.ts"; +import type { RouteInfo } from "./hop.ts"; import type * as Instance from "./instance.ts"; import type { Lister, Tracks } from "./listing.ts"; import type * as origin from "./origin.ts"; @@ -42,6 +42,12 @@ export interface Broadcast { /** Receives one change to the watched prefixes: `prefix` is now (or no longer) wanted. */ export type InterestListener = (prefix: Path.Valid, wanted: boolean) => void; +/** An origin's open request for a path, as a serving session sees it. */ +export interface RequestSlot { + /** The blind answer a session already gave it, if any. */ + readonly answer?: broadcast.Consumer; +} + /** The protocol-facing operations behind an origin producer. */ export interface OriginProducer { /** @@ -53,32 +59,34 @@ export interface OriginProducer { interests(listener: InterestListener): Dispose; /** Whether an advertised prefix overlaps the handle's allowed paths. */ accepts(prefix: Path.Valid): boolean; - receive( - prefix: Path.Valid, - route?: - | Route - | { - instance?: Route["instance"]; - epoch?: Route["epoch"]; - hops?: Route["hops"]; - cost?: Route["cost"]; - auth?: Route["auth"]; - }, - ): origin.Requests; + /** Land a route a peer announced, taken as given and never forwarded back to a peer. */ + receive(prefix: Path.Valid, route?: Partial): origin.Route; attach(discovery: boolean): Dispose; /** * Hold the origin's announcement streams overlapping `prefix` unsynced until * the returned dispose: a session holds one while its peer's initial set is in flight. */ snapshot(prefix: Path.Valid): Dispose; - readonly requests: Getter | undefined>; + readonly requests: Getter | undefined>; changed(): GetPromise; /** Whether sessions should answer the request with a blind subscription right now. */ - blind(slot: origin.RequestSlot): boolean; + blind(slot: RequestSlot): boolean; answer(path: Path.Valid, front: broadcast.Consumer): Dispose | undefined; routes(path: Path.Valid): boolean; } +/** The protocol-facing operations behind an origin route. */ +export interface Route { + /** The metadata the route is advertised with, or undefined while hidden. */ + readonly info: RouteInfo | undefined; + /** + * Advertise the route with `info` as given, as a session's update does: a named instance + * replaces the route's, which restarts its readers; otherwise it keeps the route's own. + * Announces a hidden route. + */ + update(info: Partial): void; +} + /** The protocol-facing operations behind an origin consumer. */ export interface OriginConsumer { routes(path: Path.Valid): boolean; @@ -93,7 +101,7 @@ export interface OriginConsumer { /** One originated advertisement exposed to the publishing wire. */ export interface Advertised { readonly identity: object; - readonly route: Route; + readonly route: RouteInfo; /** The paths a scoped route may serve beneath its prefix, relative like its key; unset for the whole subtree. */ readonly claim?: Path.Patterns; /** @@ -107,7 +115,7 @@ export interface Advertised { /** What names a stream: an advertisement, and the instance its route serves. */ export interface Served { readonly identity: object; - readonly route: Pick; + readonly route: Pick; } /** @@ -145,7 +153,7 @@ export interface Established { /** A produced broadcast's view, which always fetches from its own cache. */ export type Produced = Broadcast & Required>; -type View = Broadcast | OriginProducer | OriginConsumer | Established; +type View = Broadcast | OriginProducer | OriginConsumer | Route | Established; const views = new WeakMap(); /** Register the package-private view for a handle. */ @@ -167,6 +175,7 @@ export function wireOf(handle: broadcast.Producer): Produced; export function wireOf(handle: broadcast.Producer | broadcast.Consumer): Broadcast; export function wireOf(handle: origin.Producer): OriginProducer; export function wireOf(handle: origin.Consumer): OriginConsumer; +export function wireOf(handle: origin.Route): Route; export function wireOf(handle: import("./connection/established.ts").Established): Established; /** Return the package-private view for a handle. */ export function wireOf(handle: object): View { diff --git a/js/publish/src/broadcast.test.ts b/js/publish/src/broadcast.test.ts index a6a949f1a3e..4f9e0eb351b 100644 --- a/js/publish/src/broadcast.test.ts +++ b/js/publish/src/broadcast.test.ts @@ -390,7 +390,7 @@ test("serves no catalog until announced, so the first snapshot is the one at ann // Regression: a re-announce re-created the catalog track, restarting its group sequence under the // same instance, so a resumed viewer mistook the new catalog for the old one. Turning the announce off -// unannounces at once and keeps the broadcast for the next announce. +// withdraws the route at once and keeps it, broadcast and instance, for the next announce. test("a re-announce continues the catalog's group sequence", async () => { const announce = new Signal(true); const broadcast = new Broadcast({ @@ -407,6 +407,8 @@ test("a re-announce continues the catalog's group sequence", async () => { const announced = broadcast.in.origin.peek()?.follow(broadcast.in.name.peek()); const first = net.track(Broadcast.CATALOG_TRACK).subscribe().ordered(); expect((await first.nextGroup())?.sequence).toBe(0n); + const instance = announced?.active.peek()?.instance; + expect(instance).toBeDefined(); announce.set(false); await settle(); @@ -416,7 +418,9 @@ test("a re-announce continues the catalog's group sequence", async () => { announce.set(true); await settle(); - // The same track keeps serving, and its newest group is past the first. + // The follower continues the same instance, the same track keeps serving, and its newest group + // is past the first. + expect(announced?.active.peek()?.instance).toBe(instance); expect(broadcast.net.peek()).toBe(net); const group = await first.nextGroup(); expect(group?.sequence).toBeGreaterThan(0); diff --git a/js/publish/src/broadcast.ts b/js/publish/src/broadcast.ts index 0344e5004cf..da6d46ea14a 100644 --- a/js/publish/src/broadcast.ts +++ b/js/publish/src/broadcast.ts @@ -31,7 +31,7 @@ export type BroadcastInput = { // see or subscribe to it. The flip rather than a gate on creating it: tracks can be // populated while this is false, then announced once ready. The catalog is served from the // first announce, so its first snapshot is the one current at announce time. - // Turning it off unannounces the broadcast. + // Turning it off withdraws the route, and turning it back on continues the same stream. announce: Getter; // The broadcast name. @@ -445,13 +445,13 @@ export class Broadcast { ); } - // Creating into the origin outlives any single session: a reconnect re-announces the - // broadcast and new subscriptions land on the same producer. - const broadcastPublication = origin.createBroadcast(name); - const broadcast = broadcastPublication.broadcast; - // The publication mints one instance, kept across unannounce and announce, so a restart - // is a new stream rather than a resume into the old one. - effect.cleanup(() => broadcast.close()); + // Routing into the origin outlives any single session: a reconnect re-announces the + // broadcast and new subscriptions land on the same producer. Hidden until the catalog is + // served. The route mints one instance, kept across withdraw and announce, so toggling + // `announce` continues the same stream for viewers; a new route is a new stream. + const route = origin.route(name, { hidden: true }); + const broadcast = route.broadcast; + effect.cleanup(() => route.close()); // Expose it before serving so an application reacting to `net` can insert its own tracks. this.#net.set(broadcast); @@ -483,7 +483,7 @@ export class Broadcast { let serving = false; effect.run((inner) => { if (!inner.get(this.in.announce)) { - broadcastPublication.unannounce(); + route.withdraw(); return; } @@ -510,7 +510,7 @@ export class Broadcast { this.catalog.serve(track, effect); } - broadcastPublication.announce(); + route.announce(); }); // Static tracks fan out to every subscriber. The encoder-facing handle stays set while the diff --git a/js/watch/src/audio/decoder.test.ts b/js/watch/src/audio/decoder.test.ts index d87a7b73617..3a15d872cae 100644 --- a/js/watch/src/audio/decoder.test.ts +++ b/js/watch/src/audio/decoder.test.ts @@ -1180,7 +1180,7 @@ async function livePlayback(burst: number) { // Serve the same rendition from another path, as a `broadcast` override does. move(path: string) { media.peek().close(); - producer = new Moq.Origin.Producer().createBroadcast(Moq.Path.from(path)).broadcast; + producer = new Moq.Origin.Producer().route(Moq.Path.from(path), { hidden: true }).broadcast; track = producer.createTrack("audio", { timescale: Moq.Time.Timescale.MILLI, maxAge: Container.MAX_AGE }); sequence = 0n; media.set(producer.consume()); diff --git a/js/watch/src/broadcast.test.ts b/js/watch/src/broadcast.test.ts index 5f98ceeaa61..32e8ea4676a 100644 --- a/js/watch/src/broadcast.test.ts +++ b/js/watch/src/broadcast.test.ts @@ -9,10 +9,7 @@ import { Effect, Signal } from "@moq/signals"; import { Broadcast } from "./broadcast"; function publish(origin: Origin.Producer, path: Path.Valid) { - const broadcastPublication = origin.createBroadcast(path); - const broadcast = broadcastPublication.broadcast; - broadcastPublication.announce(); - return broadcast; + return origin.route(path).broadcast; } // A real origin with local broadcasts at the given paths. Resolution is proven by @@ -37,10 +34,10 @@ function broadcast(name: string, paths: string[] = [name]): { source: Broadcast; } // Answer every request `claim` receives with a new exact broadcast, returning the answers. -function serve(claim: Origin.Requests): Moq.Broadcast.Producer[] { +function serve(claim: Origin.Route): Moq.Broadcast.Producer[] { const answers: Moq.Broadcast.Producer[] = []; void (async () => { - for await (const request of claim.requested()) answers.push(request.prepare().publish().broadcast); + for await (const request of claim.requested()) answers.push(request.route().broadcast); })(); return answers; } @@ -340,16 +337,13 @@ describe("relativeBroadcast", () => { Moq.Instance.random(), Moq.Instance.random(), ]; - const catalogPublication = owner.createBroadcast(Path.from("a/b")); - const catalog = catalogPublication.broadcast; - catalogPublication.announce({ instance: catalogInstance }); - const siblingPublication = owner.createBroadcast(Path.from("a/source")); - const sibling = siblingPublication.broadcast; - siblingPublication.announce({ instance: siblingInstance }); + const catalogRoute = owner.route(Path.from("a/b"), { instance: catalogInstance }); + const catalog = catalogRoute.broadcast; + const siblingRoute = owner.route(Path.from("a/source"), { instance: siblingInstance }); + const sibling = siblingRoute.broadcast; // A route over a wire that carries no instance has one its session minted. - const plainPublication = owner.createBroadcast(Path.from("a/plain")); - const plain = plainPublication.broadcast; - plainPublication.announce({ instance: Moq.Instance.minted() }); + const plainRoute = owner.route(Path.from("a/plain"), { instance: Moq.Instance.minted() }); + const plain = plainRoute.broadcast; const source = new Broadcast({ origin: owner, name: Path.from("a/b"), @@ -387,9 +381,8 @@ describe("relativeBroadcast", () => { const owner = new Origin.Producer(); const main = publish(owner, Path.from("a/b")); const [oldInstance, newInstance] = [Moq.Instance.random(), Moq.Instance.random()]; - const oldPublication = owner.createBroadcast(Path.from("a/source")); - const old = oldPublication.broadcast; - oldPublication.announce({ instance: oldInstance }); + const oldRoute = owner.route(Path.from("a/source"), { instance: oldInstance }); + const old = oldRoute.broadcast; const source = new Broadcast({ origin: owner, name: Path.from("a/b"), @@ -413,9 +406,8 @@ describe("relativeBroadcast", () => { // The announcement is the online signal: the plain reference follows the restart, // while one naming the old instance never reads the new one. - const replacementPublication = owner.createBroadcast(Path.from("a/source")); - const replacement = replacementPublication.broadcast; - replacementPublication.announce({ instance: newInstance }); + const replacementRoute = owner.route(Path.from("a/source"), { instance: newInstance }); + const replacement = replacementRoute.broadcast; await settle(); expect(following?.instance).toBe(newInstance); expect(pinned).toBeUndefined(); @@ -433,9 +425,8 @@ describe("relativeBroadcast", () => { const owner = new Origin.Producer(); const main = publish(owner, Path.from("a/b")); const [oldInstance, newInstance] = [Moq.Instance.random(), Moq.Instance.random()]; - const oldPublication = owner.createBroadcast(Path.from("a/source")); - const old = oldPublication.broadcast; - oldPublication.announce({ instance: oldInstance }); + const oldRoute = owner.route(Path.from("a/source"), { instance: oldInstance }); + const old = oldRoute.broadcast; const named = { ...video("avc1.64001f", "./source"), instance: oldInstance } as Catalog.VideoConfig; const source = new Broadcast({ origin: owner, @@ -448,9 +439,8 @@ describe("relativeBroadcast", () => { await settle(); expect(videoRenditions(source)).toEqual(["named", "plain"]); - const replacementPublication = owner.createBroadcast(Path.from("a/source")); - const replacement = replacementPublication.broadcast; - replacementPublication.announce({ instance: newInstance }); + const replacementRoute = owner.route(Path.from("a/source"), { instance: newInstance }); + const replacement = replacementRoute.broadcast; await withoutWarnings(settle); expect(videoRenditions(source)).toEqual(["plain"]); replacement.close(); @@ -498,11 +488,11 @@ describe("blind resolution", () => { await settle(); // Stand in for a claim answering the request. - const route = owner.requests(Path.from("blind.hang")); + const route = owner.routePrefix(Path.from("blind.hang")); const requests = route.requested(); const next = await requests.next(); if (!next.value) throw new Error("expected a request"); - const upstream = next.value.prepare(Moq.Instance.random()).publish().broadcast; + const upstream = next.value.route().broadcast; await settle(); const active = source.out.active.peek(); @@ -610,7 +600,7 @@ describe("restart", () => { it("moves to a more specific announcement of another instance", async () => { const owner = new Origin.Producer(); const name = Path.from("pool/job.hang"); - const pool = owner.requests(Path.from("pool")); + const pool = owner.routePrefix(Path.from("pool")); const answers = serve(pool); const source = new Broadcast({ origin: owner, name, enabled: true, follow: true, catalogFormat: "manual" }); await settle(); @@ -618,9 +608,8 @@ describe("restart", () => { expect(old).toBeDefined(); // A newer publisher announces the path, which now serves the name: a restart. - const exactPublication = owner.createBroadcast(name); - const exact = exactPublication.broadcast; - exactPublication.announce(); + const exactRoute = owner.route(name); + const exact = exactRoute.broadcast; await settle(); const moved = source.out.active.peek(); expect(moved).toBeDefined(); @@ -642,9 +631,8 @@ describe("restart", () => { it("resumes on a covering prefix after a gap", async () => { const owner = new Origin.Producer(); const name = Path.from("pool/job.hang"); - const exactPublication = owner.createBroadcast(name); - const exact = exactPublication.broadcast; - exactPublication.announce(); + const exactRoute = owner.route(name); + const exact = exactRoute.broadcast; const source = new Broadcast({ origin: owner, name, enabled: true, follow: true, catalogFormat: "manual" }); await settle(); const old = source.out.active.peek(); @@ -653,7 +641,7 @@ describe("restart", () => { // The exact route goes, which ends the request on it, and a prefix answers before the table // is read again. The player still has to ask again. exact.close(); - const pool = owner.requests(Path.from("pool")); + const pool = owner.routePrefix(Path.from("pool")); const answers = serve(pool); await settle(); const resumed = source.out.active.peek(); @@ -671,7 +659,7 @@ describe("restart", () => { it("falls back to a covering prefix when the exact route ends", async () => { const owner = new Origin.Producer(); const name = Path.from("pool/job.hang"); - const pool = owner.requests(Path.from("pool")); + const pool = owner.routePrefix(Path.from("pool")); const answers = serve(pool); const exact = publish(owner, name); const source = new Broadcast({ origin: owner, name, enabled: true, follow: true, catalogFormat: "manual" }); @@ -704,7 +692,7 @@ describe("refusal", () => { it("reports an unroutable refusal of a restarted publisher", async () => { const owner = new Origin.Producer(); const name = Path.from("room/live.hang"); - const first = owner.requests(Path.from("room")); + const first = owner.routePrefix(Path.from("room")); const answers = serve(first); const source = new Broadcast({ origin: owner, name, enabled: true, follow: true, catalogFormat: "manual" }); await settle(); @@ -713,7 +701,7 @@ describe("refusal", () => { // The publisher restarts, and refuses with the same code an ended instance reports. first.close(); for (const answer of answers) answer.close(); - const second = owner.requests(Path.from("room")); + const second = owner.routePrefix(Path.from("room")); const refused = await second.requested().next(); refused.value?.reject(new Moq.Error.Stream(Moq.StreamCode.Unroutable, { message: "refused" })); await settle(); @@ -749,7 +737,7 @@ describe("refusal", () => { for (const follow of [true, false]) { it(`reports a refusal until a fresh request (follow: ${follow})`, async () => { const owner = new Origin.Producer(); - const route = owner.requests(Path.from("room")); + const route = owner.routePrefix(Path.from("room")); const requests = route.requested(); const name = new Signal(Path.from("room/refused.hang")); const enabled = new Signal(true); @@ -1031,7 +1019,7 @@ describe("wildcard renditions", () => { await settle(); expect(videoRenditions(source)).toEqual(["source"]); - const worker = owner.requests(Path.from(".pro/transcode")); + const worker = owner.routePrefix(Path.from(".pro/transcode")); const requests = worker.requested(); await settle(); expect(videoRenditions(source)).toEqual(["source", "transcode"]); @@ -1046,11 +1034,12 @@ describe("wildcard renditions", () => { expect(active).toBeUndefined(); if (!request) throw new Error("expected a request"); - const prepared = request.prepare(Moq.Instance.random()); - prepared.broadcast + const job = request.route({ hidden: true }); + job.broadcast .createTrack("video", { timescale: Moq.Time.Timescale.MILLI }) .writeFrame({ payload: new TextEncoder().encode("frame"), timestamp: Moq.Time.Timestamp.now() }); - const produced = prepared.publish().broadcast; + job.announce(); + const produced = job.broadcast; await settle(); expect(active).toBeDefined(); const track = active?.track("video").subscribe().ordered(); @@ -1077,8 +1066,8 @@ describe("wildcard renditions", () => { try { // A catch-all (an archive) and a narrower pool both cover the derived path. - const archive = owner.requests(Path.empty()); - const worker = owner.requests(Path.from(".pro/transcode")); + const archive = owner.routePrefix(Path.empty()); + const worker = owner.routePrefix(Path.from(".pro/transcode")); await settle(); expect(videoRenditions(source)).toEqual(["source", "transcode"]); diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts index 32f2deaf016..e8104791003 100644 --- a/js/watch/src/echo.ts +++ b/js/watch/src/echo.ts @@ -125,11 +125,11 @@ export class Echo { let broadcast: Moq.Broadcast.Producer | undefined; let writer: Report.Writer; try { - const publication = origin.createBroadcast(path); - broadcast = publication.broadcast; - writer = new Report.Writer(broadcast, Schema.TRACK, Schema.SnapshotSchema); // A fresh instance, so a reader sees a replaced feedback broadcast as a restart. - publication.announce(); + const route = origin.route(path, { hidden: true }); + broadcast = route.broadcast; + writer = new Report.Writer(broadcast, Schema.TRACK, Schema.SnapshotSchema); + route.announce(); } catch (err) { broadcast?.close(); console.warn("failed to publish feedback", path, err); diff --git a/js/watch/src/include.test.ts b/js/watch/src/include.test.ts index a8e1eab8973..67f4f2fb416 100644 --- a/js/watch/src/include.test.ts +++ b/js/watch/src/include.test.ts @@ -8,8 +8,7 @@ import { Broadcast } from "./broadcast"; import { Source } from "./video/source"; function publish(origin: Origin.Producer, path: string, instance?: Instance.Valid) { - const publication = origin.createBroadcast(Path.from(path)); - publication.announce({ instance }); + const publication = origin.route(Path.from(path), { instance }); return publication.broadcast; } @@ -104,7 +103,7 @@ it("opens a listed include only on selection, keeping its rendition IDs its own" it("reads an unavailable include as offline without touching the parent", async () => { const origin = new Origin.Producer(); publish(origin, "room/main.hang"); - const claim = origin.requests(Path.from("room/absent.hang")); + const claim = origin.routePrefix(Path.from("room/absent.hang")); const requests = claim.requested(); const source = new Broadcast({ origin, diff --git a/js/watch/src/player.test.ts b/js/watch/src/player.test.ts index d4f131d6a78..4921d4b81e6 100644 --- a/js/watch/src/player.test.ts +++ b/js/watch/src/player.test.ts @@ -35,8 +35,7 @@ test.each(["table", "consumer", "structural"] as const)("Player borrows a %s ori const player = new Player({ origin: origins[role], name, catalogFormat: "manual", catalog: {} }); try { const active = player.broadcast.out.active.changed(); - const publication = producer.createBroadcast(name); - publication.announce(); + const publication = producer.route(name); expect((await active)?.path).toBe(name); expect(player.in.origin.peek()).toBe(origins[role]); expect(player.broadcast.in.origin.peek()).toBe(origins[role]); diff --git a/js/watch/src/video/decoder.test.ts b/js/watch/src/video/decoder.test.ts index 618536e4ee1..05133fb10c7 100644 --- a/js/watch/src/video/decoder.test.ts +++ b/js/watch/src/video/decoder.test.ts @@ -437,7 +437,7 @@ async function guardedPlayback( republishMedia(path?: string): Moq.Track.Producer | undefined { media.peek().close(); mediaProducer = path - ? new Moq.Origin.Producer().createBroadcast(Moq.Path.from(path)).broadcast + ? new Moq.Origin.Producer().route(Moq.Path.from(path), { hidden: true }).broadcast : new Moq.Broadcast.Producer(); const track = live ? mediaProducer.createTrack("video", { timescale: Moq.Time.Timescale.MILLI, maxAge: Container.MAX_AGE }) diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 77428b07a6b..73bb90e54be 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -25,6 +25,22 @@ while (true) { } ``` +### Publishing goes through one `Route` + +`OriginProducer.createBroadcast(path)`, `Moq.createBroadcast`, and `Server.createBroadcast` are `route(path, RouteOptions())`, and `OriginProducer.requests(prefix)` is `routePrefix(prefix, RouteOptions())`. Both return a `Route`, which replaces `Publication`, `OriginRequests`, and `BroadcastPrepared`: + +- `Publication.broadcast()` is `Route.broadcast()`, which throws `MoqException.Internal` on a prefix route. +- `Publication.announce(AnnounceRoute(...))` is `announce()`, and re-pricing is `setCost(cost)`. `unannounce()` is `withdraw()`. +- `OriginRequests.requestedBroadcast()` is `Route.requested()`, which returns null once the origin closes; `requestedBroadcasts()` is now an extension on `Route`, and ending its collection no longer retracts the route. +- `BroadcastRequest.prepare()` then `BroadcastPrepared.publish()` is `BroadcastRequest.route(options)`: create it hidden to fill it first, then `announce()`. +- `Route.instance()` is the stream's instance, minted at creation and kept across `withdraw` and `announce`. + +`AnnounceRoute` is `RouteOptions(hidden, cost, instance, epoch)`, given once at creation. A route is visible at once unless `hidden = true`; set it and call `announce()` after filling the catalog to keep the old create-then-announce order. A stable `instance` is fixed for the route's lifetime: announcing another one is a new route. + +Hold the `Route` for as long as the broadcast should stay announced: closing or cancelling it retracts it, while `BroadcastProducer.end()` still ends both. A `BroadcastProducer` alone no longer keeps it announced. + +`Route`, the received facts in `Announce.route`, is renamed `RouteInfo`; its fields are unchanged. + ### Catalog renditions carry their warmup ([#7864](https://github.com/moq-dev/moq/pull/7864)) `Video` and `Audio` gain `warmup`, the catalog's decoder warmup; it defaults to `null` as the last field, so existing code keeps working. `TrackConsumer` and the audio and video consumers read it from the rendition and start that much earlier. diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index e60a13736c6..356134c8b47 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -49,14 +49,16 @@ typealias Request = uniffi.moq.MoqRequest typealias Transport = uniffi.moq.MoqTransport // Origin (broadcast discovery / announcement). -/** The publish side of an origin: create broadcasts so subscribers can discover them. */ +/** The publish side of an origin: create routes so subscribers can discover them. */ typealias OriginProducer = uniffi.moq.MoqOriginProducer /** - * An origin's handle on one broadcast: `broadcast()` to fill it, `announce` and `unannounce` to - * advertise it. + * A route on an origin: an exact route owning one broadcast (`broadcast()` to fill it), or a prefix + * route yielding the requests beneath it (`requested()`). `announce`, `withdraw`, and `setCost` + * advertise it. Closing or cancelling it retracts it, as does ending its broadcast; a broadcast + * handle alone does not keep it announced. */ -typealias Publication = uniffi.moq.MoqPublication +typealias Route = uniffi.moq.MoqRoute /** Config for creating an origin, such as its total cache budget. */ typealias OriginConfig = uniffi.moq.MoqOriginConfig @@ -64,15 +66,9 @@ typealias OriginConfig = uniffi.moq.MoqOriginConfig /** The subscribe side of an origin: discover and request published broadcasts. */ typealias OriginConsumer = uniffi.moq.MoqOriginConsumer -/** A served route: advertises a path prefix and yields broadcast requests beneath it. */ -typealias OriginRequests = uniffi.moq.MoqOriginRequests - -/** A requested broadcast not yet accepted: fulfill it with a producer or reject it. */ +/** A requested broadcast not yet answered: serve it, route it, or reject it. */ typealias BroadcastRequest = uniffi.moq.MoqBroadcastRequest -/** A claim answer being filled before its exact route is announced. */ -typealias BroadcastPrepared = uniffi.moq.MoqBroadcastPrepared - /** A stream of announce events under a prefix. */ typealias AnnounceConsumer = uniffi.moq.MoqAnnounceConsumer @@ -156,17 +152,17 @@ typealias Frame = uniffi.moq.MoqFrame typealias Timestamp = uniffi.moq.MoqTimestamp /** - * How a broadcast advertises its exact path: its static production cost (lower wins), an optional - * stable instance (null keeps the one the broadcast minted), and the epoch, which only matters with - * a stable instance. + * How a [Route] advertises itself: `hidden` until `announce`, its static production cost (lower + * wins), an optional stable instance (null mints a fresh one the route keeps for its lifetime), and + * the epoch, which only matters with a stable instance. */ -typealias AnnounceRoute = uniffi.moq.MoqAnnounceRoute +typealias RouteOptions = uniffi.moq.MoqRouteOptions /** - * An observed path-prefix route: the instance of the stream it serves, relay hop ids (oldest - * first), and static production and link cost (lower wins). + * The read-only facts on a received route: the instance of the stream it serves, relay hop ids + * (oldest first), and static production and link cost (lower wins). */ -typealias Route = uniffi.moq.MoqRoute +typealias RouteInfo = uniffi.moq.MoqRouteInfo /** Tunes how a track subscription is delivered: priority, delay, ranges, and group ordering. */ typealias Subscription = uniffi.moq.MoqSubscription diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt index 1cb73bbe325..bf2fc6a62bc 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt @@ -47,9 +47,11 @@ fun BroadcastRequests.requestedTracks(): Flow = /** Stream of the fills readers of one track need. */ fun TrackRequests.requestedFills(): Flow = pull({ cancel() }) { requestedFill() } -/** Stream of broadcasts requested by consumers. */ -fun OriginRequests.requestedBroadcasts(): Flow = - pull({ cancel() }) { requestedBroadcast() } +/** + * Stream of broadcasts requested beneath a prefix route, ending once the origin closes. Ending the + * collection leaves the route advertised; close or cancel the route to retract it. + */ +fun Route.requestedBroadcasts(): Flow = pull { requested() } /** Stream of timestamped raw frames within a group. */ fun GroupConsumer.frames(): Flow = pull({ cancel() }) { readFrame() } diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt index 89b15bc41a6..c7d738c2eb4 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt @@ -4,8 +4,8 @@ package dev.moq * A MoQ session with publish/subscribe conveniences. * * Build one with [Moq.connect]. The underlying [session] always exposes a publisher and a - * subscriber (wired from the origins in its [ClientConfig], or auto-created), so you can - * [createBroadcast] and collect [announced] updates without touching the raw [Client] handle. + * subscriber (wired from the origins in its [ClientConfig], or auto-created), so you can [route] + * and collect [announced] updates without touching the raw [Client] handle. * * Call [shutdown], then await [Session.closed] to drain finished tracks before disconnecting. * [AutoCloseable] disposal through `use { ... }` or [close] cancels immediately. @@ -17,13 +17,14 @@ internal constructor( private val client: Client, ) : AutoCloseable { /** - * Create an unannounced broadcast at [path], invisible to everyone until announced. + * Create a route at exactly [path], owning a new broadcast to fill. * - * Fill `broadcast()`, then advertise it with `announce`. The broadcast's `end()` ends it for - * good, as does releasing its last handle: the publication, each `broadcast()`, and - * `requests()`. + * Visible at once unless [options] is `hidden`: then fill `broadcast()` and advertise it with + * `announce()`. Hold the route while it should stay announced: closing it retracts it, and the + * broadcast's `end()` ends both. */ - fun createBroadcast(path: String): Publication = session.publish().createBroadcast(path) + fun route(path: String, options: RouteOptions = RouteOptions()): Route = + session.publish().route(path, options) /** * List the paths matching [config] as each becomes present or absent; prefixes stay relative to diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Server.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Server.kt index 25a4547156c..033e46d1f88 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Server.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Server.kt @@ -9,8 +9,8 @@ import uniffi.moq.MoqServer /** * A listening MoQ server with publish/subscribe conveniences. * - * Build one with [Server.listen]. Broadcasts created via [createBroadcast] are served to incoming - * sessions, and [requests] streams each incoming [Request] for the caller to accept or reject. + * Build one with [Server.listen]. Broadcasts created via [route] are served to incoming sessions, + * and [requests] streams each incoming [Request] for the caller to accept or reject. * * [Server] is [AutoCloseable]; `use { ... }` (or [close]) stops accepting new sessions. In-flight * sessions stay alive until their handles are dropped or cancelled. @@ -24,15 +24,15 @@ internal constructor( private val publishOrigin: OriginProducer?, ) : AutoCloseable { /** - * Create an unannounced broadcast at [path], served to incoming sessions once announced. + * Create a route at exactly [path], served to incoming sessions while announced. * - * Fill `broadcast()`, then advertise it with `announce`. The broadcast's `end()` ends it for - * good, as does releasing its last handle: the publication, each `broadcast()`, and - * `requests()`. + * Visible at once unless [options] is `hidden`: then fill `broadcast()` and advertise it with + * `announce()`. Hold the route while it should stay announced: closing it retracts it, and the + * broadcast's `end()` ends both. */ - fun createBroadcast(path: String): Publication { + fun route(path: String, options: RouteOptions = RouteOptions()): Route { val origin = publishOrigin ?: throw IllegalStateException("no publish origin configured") - return origin.createBroadcast(path) + return origin.route(path, options) } /** diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 9c40670f10d..bdb48cef8c3 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -30,6 +30,7 @@ import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFailsWith import kotlin.test.assertIs +import kotlin.test.assertNotEquals import kotlin.test.assertNotNull import kotlin.test.assertNull import kotlin.test.assertTrue @@ -210,7 +211,7 @@ class SmokeTest { fun `origin alias constructs and consumes`() = runTest { OriginProducer(OriginConfig()).use { origin -> origin.consume().use { /* lifecycle smoke */ } - origin.requests("").use { /* dynamic origin smoke */ } + origin.routePrefix("", RouteOptions()).use { /* prefix route smoke */ } } } @@ -690,9 +691,9 @@ class SmokeTest { assertEquals(1, fingerprints.size) assertEquals(64, fingerprints[0].length) - server.createBroadcast("live").use { publication -> - publication.announce(AnnounceRoute()) - publication.unannounce() + server.route("live", RouteOptions(hidden = true)).use { route -> + route.announce() + route.withdraw() } } } @@ -772,57 +773,75 @@ class SmokeTest { @Test fun `a broadcast is reachable only while announced`() = runTest { OriginProducer(OriginConfig()).use { origin -> - origin.createBroadcast("live").use { publication -> - publication.broadcast().use { it.publishTrack("events", null) } + origin.route("live", RouteOptions(hidden = true)).use { route -> + route.broadcast().use { it.publishTrack("events", null) } val consumer = origin.consume() assertFailsWith { consumer.request("live") } - publication.announce(AnnounceRoute()) + route.announce() val announced = consumer.announced(AnnounceConfig()) val first = assertIs(announced.nextRoute()) assertEquals("live", first.announce.prefix) + assertEquals(route.instance(), first.announce.route.instance) - publication.unannounce() + route.withdraw() val retracted = assertIs(announced.nextRoute()) assertEquals("live", retracted.announce.prefix) assertFailsWith { consumer.request("live") } - publication.announce(AnnounceRoute()) - assertIs(announced.nextRoute()) + // Announcing again continues the same stream. + route.announce() + val again = assertIs(announced.nextRoute()) + assertEquals(route.instance(), again.announce.route.instance) consumer.request("live") } } } @Test - fun `closing a publication keeps its route until the broadcast ends`() = runTest { + fun `closing a route retracts it while its broadcast lives on`() = runTest { OriginProducer(OriginConfig()).use { origin -> val consumer = origin.consume() val announced = consumer.announced(AnnounceConfig()) - val publication = origin.createBroadcast("live") - publication.broadcast().use { broadcast -> - publication.use { it.announce(AnnounceRoute()) } + val route = origin.route("live", RouteOptions()) + route.broadcast().use { broadcast -> assertIs(announced.nextRoute()) consumer.request("live") + route.close() + assertIs(announced.nextRoute()) + assertFailsWith { consumer.request("live") } + broadcast.publishTrack("events", null) broadcast.end() + } + } + } + + @Test + fun `ending the broadcast retracts its route`() = runTest { + OriginProducer(OriginConfig()).use { origin -> + val consumer = origin.consume() + val announced = consumer.announced(AnnounceConfig()) + origin.route("live", RouteOptions()).use { route -> + assertIs(announced.nextRoute()) + route.broadcast().use { it.end() } assertIs(announced.nextRoute()) assertFailsWith { consumer.request("live") } + assertFailsWith { route.announce() } } } } @Test - fun `a stale publication leaves its replacement alone`() = runTest { + fun `a stale route leaves its replacement alone`() = runTest { OriginProducer(OriginConfig()).use { origin -> - origin.createBroadcast("live").use { stale -> - stale.announce(AnnounceRoute()) + origin.route("live", RouteOptions()).use { stale -> stale.broadcast().use { it.end() } - origin.createBroadcast("live").use { replacement -> - replacement.announce(AnnounceRoute()) - assertFailsWith { stale.announce(AnnounceRoute()) } - assertFailsWith { stale.unannounce() } + origin.route("live", RouteOptions()).use { replacement -> + assertFailsWith { stale.announce() } + assertFailsWith { stale.setCost(1uL) } + stale.withdraw() origin.consume().request("live") replacement.broadcast().use { it.end() } } @@ -836,22 +855,25 @@ class SmokeTest { val consumer = origin.consume() val announced = consumer.announced(AnnounceConfig()) val following = consumer.follow("instance", null) - origin.createBroadcast("instance").use { publication -> - publication.announce(AnnounceRoute()) + origin.route("instance", RouteOptions()).use { first -> val present = assertIs(announced.nextRoute()) assertTrue(present.announce.route.instance.isNotEmpty()) + assertEquals(first.instance(), present.announce.route.instance) assertNotNull(following.available()).close() - publication.announce(AnnounceRoute(instance = "camera", epoch = 1uL)) - assertNotNull(following.available()).close() + origin.route("instance", RouteOptions(instance = "camera", epoch = 1uL)).use { + second -> + assertNotNull(following.available()).close() - // The takeover was not listed, so the next event is the path going absent. - publication.unannounce() - val absent = assertIs(announced.nextRoute()) - assertEquals("camera", absent.announce.route.instance) + // The takeover was not listed, so the next event is the path going absent. + first.withdraw() + second.withdraw() + val absent = assertIs(announced.nextRoute()) + assertEquals("camera", absent.announce.route.instance) + } assertFailsWith { - publication.announce(AnnounceRoute(instance = "")) + origin.route("refused", RouteOptions(instance = "")) } } following.cancel() @@ -862,14 +884,13 @@ class SmokeTest { fun `a follower reports the path going offline and the next broadcast`() = runTest { OriginProducer(OriginConfig()).use { origin -> val following = origin.consume().follow("offline", null) - origin.createBroadcast("offline").use { publication -> - publication.announce(AnnounceRoute()) + origin.route("offline", RouteOptions()).use { route -> assertNotNull(following.available()).close() - publication.unannounce() + route.withdraw() assertNull(following.available()) - publication.announce(AnnounceRoute()) + route.announce() assertNotNull(following.available()).close() } following.cancel() @@ -881,8 +902,7 @@ class SmokeTest { OriginProducer(OriginConfig()).use { origin -> val announced = origin.consume().announced(AnnounceConfig(prefix = "room", filter = "*/chat")) - origin.createBroadcast("room/alice/chat").use { publication -> - publication.announce(AnnounceRoute()) + origin.route("room/alice/chat", RouteOptions()).use { val update = assertIs(announced.nextRoute()) assertEquals("room/alice/chat", update.announce.prefix) assertEquals(listOf("alice"), update.announce.captures) @@ -893,21 +913,23 @@ class SmokeTest { @Test fun `dynamic serves a request under a prefix`() = runTest { OriginProducer(OriginConfig()).use { origin -> - origin.requests("live").use { dynamic -> + origin.routePrefix("live", RouteOptions()).use { dynamic -> + assertFailsWith { dynamic.broadcast() } val pending = async { origin.consume().request("live/cam") } - val request = dynamic.requestedBroadcast() + val request = assertNotNull(dynamic.requested()) assertEquals("live/cam", request.path()) - request.prepare().use { prepared -> - prepared.broadcast().use { fill -> - prepared.publish().use { publication -> - pending.await() - // The publication fills the broadcast it prepared: ending one ends the - // other. - publication.broadcast().use { it.end() } - assertFailsWith { fill.publishTrack("late", null) } - } + request.route(RouteOptions(hidden = true)).use { job -> + assertNotEquals(dynamic.instance(), job.instance()) + job.broadcast().use { fill -> + // Only announcing answers the requester. + job.announce() + pending.await() + // The route hands out one broadcast: ending it ends the route too. + job.broadcast().use { it.end() } + assertFailsWith { fill.publishTrack("late", null) } + assertFailsWith { job.announce() } } } } @@ -1044,8 +1066,8 @@ class SmokeTest { @Test fun `audio consumer reports its playout delay`() = runTest { OriginProducer(OriginConfig()).use { origin -> - origin.createBroadcast("audio-delay").use { publication -> - publication.broadcast().use { broadcast -> + origin.route("audio-delay", RouteOptions(hidden = true)).use { route -> + route.broadcast().use { broadcast -> val audio = AudioProducer( CatalogProducer(broadcast), @@ -1060,7 +1082,7 @@ class SmokeTest { track = "mic", ), ) - publication.announce(AnnounceRoute()) + route.announce() val consumer = origin.consume().request("audio-delay") val catalog = CatalogConsumer.subscribe(consumer).next()!! @@ -1116,8 +1138,8 @@ class SmokeTest { @Test fun `decoded video frame owns its picture`() = runTest { OriginProducer(OriginConfig()).use { origin -> - origin.createBroadcast("video-decode-frame").use { publication -> - publication.broadcast().use { broadcast -> + origin.route("video-decode-frame", RouteOptions(hidden = true)).use { route -> + route.broadcast().use { broadcast -> val video = VideoProducer( CatalogProducer(broadcast), @@ -1138,7 +1160,7 @@ class SmokeTest { bandwidth = null, ), ) - publication.announce(AnnounceRoute()) + route.announce() // Seed the track so a subscriber joining below lands on encoded media. val rgba = ByteArray(320 * 240 * 4) { 0x80.toByte() } diff --git a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt index 1fa325f5e59..d66b8fa64aa 100644 --- a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt +++ b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt @@ -83,8 +83,8 @@ class FfiBench { kotlinx.coroutines.coroutineScope { // Close every handle inside the case, so native teardown never lands in a later one. val origin = OriginProducer(OriginConfig(cacheCapacityBytes = CACHE_BYTES)) - val publication = origin.createBroadcast("bench") - val broadcast = publication.broadcast() + val route = origin.route("bench", RouteOptions(hidden = true)) + val broadcast = route.broadcast() val tracks = (0 until case.publishers).map { broadcast.publishTrack("$it", TrackInfo(timescale = 1_000_000uL)) @@ -142,7 +142,7 @@ class FfiBench { val mb = (n - WARMUP) * case.delivered / 1e6 results += Result("throughput/${case.name}", "MB/s", mb / (wallNs / 1e9)) results += Result("cpu/${case.name}", "ms/MB", cpuUsedNs / 1e6 / mb) - (consumers + tracks + listOf(broadcast, publication, origin)).forEach { it.close() } + (consumers + tracks + listOf(broadcast, route, origin)).forEach { it.close() } } private inline fun call(name: String, results: MutableList, fn: () -> Unit) { diff --git a/py/moq-ffi/tests/exit_inside_callback.py b/py/moq-ffi/tests/exit_inside_callback.py index 9e2ec2038de..6520a4cd2a9 100644 --- a/py/moq-ffi/tests/exit_inside_callback.py +++ b/py/moq-ffi/tests/exit_inside_callback.py @@ -54,9 +54,8 @@ def _preempted_continuation(future_ptr, poll_code): async def main() -> None: origin = moq_ffi.MoqOriginProducer(moq_ffi.MoqOriginConfig()) - publication = origin.create_broadcast("exit") - publication.announce(moq_ffi.MoqAnnounceRoute()) - broadcast = publication.broadcast() + route = origin.route("exit", moq_ffi.MoqRouteOptions()) + broadcast = route.broadcast() track = broadcast.publish_track("data", moq_ffi.MoqTrackInfo(timescale=1_000_000)) consumer = await origin.consume().request("exit") diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index eba8ff96742..e4974c0906f 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -16,6 +16,20 @@ Another publisher instance taking a path over keeps it present and is not listed Later calls return `None` when the path goes offline, or, when following an `instance`, when another instance takes it over, then the next broadcast once something serves the path again; the first call never returns `None`. Stop reading the previous broadcast on `None` and call `available()` again. A caller that only awaits the first broadcast can assert it is not `None`. +### Publishing goes through one `Route` handle + +`OriginProducer.create_broadcast(path)` (and `Client.create_broadcast` / `Server.create_broadcast`) is `route(path, *, hidden=False, cost=0, instance=None, epoch=0)`, and `OriginProducer.requests(prefix)` is `route_prefix(prefix, ...)`. Both return a `moq.Route`, which replaces `Publication`, `OriginRequests`, and `BroadcastPrepared`: + +- `Publication.broadcast` is `Route.broadcast`, which raises `Error.Internal` on a prefix route. +- `Publication.announce(AnnounceRoute(...))` is `Route.announce()`; pass the cost and instance to `route()` instead, and re-price with `set_cost(cost)`. `unannounce()` is `withdraw()`. +- `OriginRequests.requested_broadcast()` is `Route.requested()`, which returns `None` once the origin closes; `async for` still iterates the requests. +- `BroadcastRequest.prepare()` then `.publish()` is `BroadcastRequest.route(hidden=True)`, then fill `.broadcast` and call `announce()`. +- `Route.instance` is the stream's instance, minted at creation and kept across `withdraw()` and `announce()`. + +A route is visible at once unless `hidden=True`, so pass it and call `announce()` after filling the catalog to keep the old create-then-announce order. Hold the `Route` while the broadcast should stay announced: dropping or cancelling it retracts it, while `broadcast.close()` still ends both. + +`AnnounceRoute` is gone, and `moq.Route` now names the handle: the read-only facts on `Announce.route` are `moq.RouteInfo`. + ### Catalog renditions carry their warmup ([#7864](https://github.com/moq-dev/moq/pull/7864)) `Video` and `Audio` gain `warmup`, the catalog's decoder warmup; it defaults to `None` as the last field, so existing code keeps working. `TrackConsumer` and the audio and video consumers read it from the rendition and start that much earlier. diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index bbaa3f5ae16..b09a547121e 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -57,8 +57,9 @@ import moq async def main(): async with moq.Client("https://cdn.moq.dev/anon") as client: - publication = client.create_broadcast("my-stream") - broadcast = publication.broadcast + # Hidden until announced; hold the route, since dropping it retracts the broadcast. + route = client.route("my-stream", hidden=True) + broadcast = route.broadcast # Publish an Opus audio track (init bytes from your encoder) audio = moq.media.TrackProducer.audio( @@ -72,8 +73,8 @@ async def main(): audio.write_frame(payload, timestamp=moq.Timestamp(20, 1_000)) audio.cut() - # Each broadcast mints a fresh instance, so viewers see a restart as a new stream. - publication.announce() + # Each route mints a fresh instance, so viewers see a restart as a new stream. + route.announce() # Clean up audio.finish() @@ -92,9 +93,9 @@ import moq async def main(): async with moq.Server("127.0.0.1:4443", tls_generate=["localhost"]) as server: - publication = server.create_broadcast("hello") - track = publication.broadcast.publish_track("events") - publication.announce() + route = server.route("hello", hidden=True) + track = route.broadcast.publish_track("events") + route.announce() print(f"listening on https://{server.local_addr}") sessions = [] @@ -148,7 +149,7 @@ client = moq.Client( - `keylog`. Write TLS session secrets to the file `SSLKEYLOGFILE` names, for decrypting a capture; without `SSLKEYLOGFILE` entering the server fails. - `.local_addr`. The bound address (useful when binding to port `0`). - `.cert_fingerprints()`. SHA-256 fingerprints of the configured TLS certificates, for `serverCertificateHashes` browser cert pinning. - - `.create_broadcast(path) → Publication`. Create an unannounced broadcast, invisible to everyone; fill `.broadcast`, then `announce()` makes it discoverable and reachable; `.broadcast.close()` ends it. + - `.route(path, *, hidden=False, cost=0, instance=None, epoch=0) → Route`. Create a route owning a broadcast to fill at `.broadcast`. Create it `hidden` to fill it before `announce()` makes it discoverable and reachable; dropping or cancelling the route retracts it, and `.broadcast.close()` ends both. - **`Request`**. An incoming session, yielded by `async for request in server`. - `.url`, `.path`, `.query`, `.transport`. The query-free path is uniform across transports; the root or missing path is `""`. The encoded query may contain credentials. - `await .accept(*, publish=None, consume=None) → Session`. Origins are captured when accept starts; None inherits the server default and a supplied origin replaces it. Pass fresh origins for isolation, or the same origin on both sides to share it. A second response raises `AlreadyResponded`; calls after cancel raise `Cancelled`. Complete the handshake (hold the result to keep the connection alive). @@ -245,20 +246,19 @@ same either way. Opaque bytes go on a plain `TrackProducer`. - **`GroupConsumer`**. Async iterator of raw `Frame`s. - `.read_frame() -> Frame | None` returns a raw frame with optional capture time. -Every handle whose cleanup is `cancel()` is an async context manager, so exiting `async with` releases it: the consumers (`media.CatalogConsumer`, `media.TrackConsumer`, `media.GroupConsumer`, `TrackConsumer`, `audio.Consumer`, `video.Consumer`, `GroupConsumer`, `json.SnapshotConsumer`, `json.StreamConsumer`, `json.WindowConsumer`, `AnnounceConsumer`, `Following`) and the dynamic sources (`OriginRequests`, `BroadcastRequests`, `TrackRequests`). +Every handle whose cleanup is `cancel()` is an async context manager, so exiting `async with` releases it: the consumers (`media.CatalogConsumer`, `media.TrackConsumer`, `media.GroupConsumer`, `TrackConsumer`, `audio.Consumer`, `video.Consumer`, `GroupConsumer`, `json.SnapshotConsumer`, `json.StreamConsumer`, `json.WindowConsumer`, `AnnounceConsumer`, `Following`) and the dynamic sources (`Route`, `BroadcastRequests`, `TrackRequests`). ### Origin (advanced) - **`OriginProducer(*, cache_capacity_bytes=None)`**. Manage broadcast announcements. Set `cache_capacity_bytes` to bound cached groups under this origin. - `.consume() → OriginConsumer` - - `.requests(prefix) → OriginRequests` - - `.create_broadcast(path) → Publication` -- **`Publication`**. A broadcast published on an origin. Dropping it keeps the route; closing the broadcast ends it. - - `.broadcast → BroadcastProducer`. The broadcast to fill. - - `.announce(route=None)`, `.unannounce()`. Advertise or retract its exact path; both raise `Closed` once the broadcast closed. -- **`OriginRequests`**. Async source of broadcasts requested by consumers. - - `await .requested_broadcast() → BroadcastRequest`. Call `.serve(consumer)` to answer with held content under the prefix route's continuous sequence space, `.prepare()` then fill its `.broadcast` and `.publish() → Publication` for an independently restarting job under a fresh instance, or `.reject(code)` to fail the requester. - - Async iterator yielding `BroadcastRequest` + - `.route(path, *, hidden=False, cost=0, instance=None, epoch=0) → Route`. An exact route owning a new broadcast, visible at once unless `hidden`, under a fresh instance unless `instance` names one. + - `.route_prefix(prefix, *, hidden=False, cost=0, instance=None, epoch=0) → Route`. A prefix route that yields the requests beneath it. +- **`Route`**. A route on an origin. Hold it: dropping or cancelling it retracts it, and so does closing its broadcast. + - `.broadcast → BroadcastProducer`. The broadcast an exact route owns; raises `Internal` on a prefix route. + - `.instance`. The stream it serves, kept across `withdraw()` and `announce()`. + - `.announce()`, `.withdraw()`, `.set_cost(cost)`. Show, hide, or re-price it in place; `announce` and `set_cost` raise `Closed` once the broadcast closed. + - `await .requested() → BroadcastRequest | None`, or async iteration over a prefix route. Call `.serve(consumer)` to answer with held content under the prefix route's continuous sequence space, `.route(hidden=..., ...)` for the path's own route under a fresh instance, as an independently restarting job, or `.reject(code)` to fail the requester. - **`OriginConsumer`**. Discover broadcasts. - `.announced(prefix, filter=None) → AnnounceConsumer` (async iterator of `AnnounceEvent`: `AnnounceEventPresent` or `AnnounceEventAbsent`, each carrying an `Announce` whose `.route.instance` names the stream; another instance taking a path over keeps it present, so `follow` the path to see that); `filter` is a pattern relative to the literal prefix, while each `Announce.prefix` stays origin-relative and `.captures` is a required list of wildcard matches, empty without wildcards - `.follow(path, instance=None) → Following` (awaitable, waits until something serves the path, then returns each stream that takes over, or `None` once the path goes offline; an `instance` follows only that stream) diff --git a/py/moq-rs/benches/ffi.py b/py/moq-rs/benches/ffi.py index f5049c4cad2..120441b4228 100644 --- a/py/moq-rs/benches/ffi.py +++ b/py/moq-rs/benches/ffi.py @@ -70,7 +70,8 @@ async def read(case: Case, consumer: moq.TrackConsumer, payload: bytes, n: int) async def throughput(case: Case, results: list[dict]) -> None: origin = moq.OriginProducer(cache_capacity_bytes=CACHE_BYTES) - broadcast = origin.create_broadcast("bench").broadcast + route = origin.route("bench", hidden=True) + broadcast = route.broadcast tracks = [broadcast.publish_track(str(p), moq.TrackInfo(timescale=1_000_000)) for p in range(case.publishers)] consumers = [track.consume() for track in tracks for _ in range(case.subscribers)] # A non-uniform payload, so a zero-filled or truncated copy fails the check. diff --git a/py/moq-rs/docs/index.md b/py/moq-rs/docs/index.md index fcb8b948027..af3f45afdfd 100644 --- a/py/moq-rs/docs/index.md +++ b/py/moq-rs/docs/index.md @@ -170,8 +170,7 @@ broadcast, and producers advertise it in the catalog. OriginProducer OriginConsumer - OriginRequests - Publication + Route AnnounceConsumer Following Announce @@ -216,8 +215,7 @@ Rust side ([`moq-ffi`](https://crates.io/crates/moq-ffi)). Subscription TrackInfo FetchGroupOptions - AnnounceRoute - Route + RouteInfo ConnectionStats ``` diff --git a/py/moq-rs/examples/clock.py b/py/moq-rs/examples/clock.py index 4df4e102f8b..d251cecf3ce 100644 --- a/py/moq-rs/examples/clock.py +++ b/py/moq-rs/examples/clock.py @@ -17,9 +17,9 @@ async def publish(url: str, broadcast_name: str, track_name: str, insecure: bool) -> None: async with moq.Client(url, tls=moq.ClientTls(insecure=insecure)) as client: - publication = client.create_broadcast(broadcast_name) - track = publication.broadcast.publish_track(track_name, moq.TrackInfo(timescale=1_000_000)) - publication.announce() + route = client.route(broadcast_name, hidden=True) + track = route.broadcast.publish_track(track_name, moq.TrackInfo(timescale=1_000_000)) + route.announce() print(f"publishing {broadcast_name!r} track={track_name!r} at {url}") while True: diff --git a/py/moq-rs/examples/serve_clock.py b/py/moq-rs/examples/serve_clock.py index 5df6325cb1a..01e4871700a 100644 --- a/py/moq-rs/examples/serve_clock.py +++ b/py/moq-rs/examples/serve_clock.py @@ -20,9 +20,9 @@ async def run(bind: str, broadcast_name: str, track_name: str, host: str) -> None: async with moq.Server(bind, tls_generate=[host]) as server: - publication = server.create_broadcast(broadcast_name) - track = publication.broadcast.publish_track(track_name, moq.TrackInfo(timescale=1_000_000)) - publication.announce() + route = server.route(broadcast_name, hidden=True) + track = route.broadcast.publish_track(track_name, moq.TrackInfo(timescale=1_000_000)) + route.announce() print(f"serving {broadcast_name!r} track={track_name!r} on https://{server.local_addr}") for fp in server.cert_fingerprints(): print(f" cert fingerprint sha256: {fp}") diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index b5b74fc4c2b..713abae9278 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -20,13 +20,11 @@ AnnounceEvent, AnnounceEventAbsent, AnnounceEventPresent, - BroadcastPrepared, BroadcastRequest, Following, OriginConsumer, OriginProducer, - OriginRequests, - Publication, + Route, ) from .publish import ( BroadcastProducer, @@ -57,7 +55,6 @@ ) from .types import ( Anchor, - AnnounceRoute, AudioCodec, AudioEncoderInput, AudioSampleFormat, @@ -80,7 +77,7 @@ QuicConfig, Range, RateTarget, - Route, + RouteInfo, Subscription, Timestamp, TrackInfo, @@ -101,7 +98,6 @@ "AnnounceEvent", "AnnounceEventAbsent", "AnnounceEventPresent", - "AnnounceRoute", "AudioCodec", "AudioEncoderInput", "AudioSampleFormat", @@ -109,7 +105,6 @@ "BandwidthConsumer", "BroadcastConsumer", "BroadcastRequests", - "BroadcastPrepared", "BroadcastProducer", "BroadcastRequest", "Client", @@ -139,17 +134,16 @@ "GroupConsumer", "GroupProducer", "OriginConsumer", - "OriginRequests", "OriginProducer", "Order", "Position", - "Publication", "Range", "RateControl", "RateTarget", "Request", "Reservation", "Route", + "RouteInfo", "Server", "Session", "Subscription", diff --git a/py/moq-rs/moq/client.py b/py/moq-rs/moq/client.py index 2394adea5df..c65e489bb0a 100644 --- a/py/moq-rs/moq/client.py +++ b/py/moq-rs/moq/client.py @@ -14,7 +14,7 @@ ) from ._records import Backoff, ClientTls, QuicConfig, WebSocketConfig, _implementation, _strs -from .origin import AnnounceConsumer, Following, OriginConsumer, OriginProducer, Publication +from .origin import AnnounceConsumer, Following, OriginConsumer, OriginProducer, Route from .session import Session from .subscribe import BroadcastConsumer @@ -155,12 +155,14 @@ async def __aexit__(self, *exc) -> None: self._inner.cancel() self._inner = None - def create_broadcast(self, path: str) -> Publication: - """Create an unannounced broadcast at ``path``, invisible until announced. Announce it after populating tracks. + def route( + self, path: str, *, hidden: bool = False, cost: int = 0, instance: str | None = None, epoch: int = 0 + ) -> Route: + """Create a route at ``path`` owning a broadcast to fill; hold it to keep it announced. - See :meth:`OriginProducer.create_broadcast`. + See :meth:`OriginProducer.route`. """ - return self._require_publisher().create_broadcast(path) + return self._require_publisher().route(path, hidden=hidden, cost=cost, instance=instance, epoch=epoch) def announced(self, prefix: str = "", *, filter: str | None = None, hidden: bool = False) -> AnnounceConsumer: """Async-iterate broadcasts under ``prefix`` matching an optional pattern. diff --git a/py/moq-rs/moq/origin.py b/py/moq-rs/moq/origin.py index 090aabc1c53..fac2485f231 100644 --- a/py/moq-rs/moq/origin.py +++ b/py/moq-rs/moq/origin.py @@ -7,20 +7,18 @@ MoqAnnounceConfig, MoqAnnounceConsumer, MoqAnnounceEvent, - MoqBroadcastPrepared, MoqBroadcastRequest, MoqFollowing, MoqOriginConfig, MoqOriginConsumer, MoqOriginProducer, - MoqOriginRequests, - MoqPublication, + MoqRoute, + MoqRouteOptions, ) from ._stream import _Stream from .publish import BroadcastProducer from .subscribe import BroadcastConsumer -from .types import AnnounceRoute Announce = MoqAnnounce """A route over a prefix: the origin-relative ``prefix``, what each filter wildcard @@ -103,8 +101,12 @@ def cancel(self) -> None: self._inner.cancel() +def _options(*, hidden: bool, cost: int, instance: str | None, epoch: int) -> MoqRouteOptions: + return MoqRouteOptions(hidden=hidden, cost=cost, instance=instance, epoch=epoch) + + class BroadcastRequest: - """A requested broadcast that has not been accepted yet.""" + """A requested broadcast that has not been answered yet.""" def __init__(self, inner: MoqBroadcastRequest) -> None: self._inner = inner @@ -114,9 +116,16 @@ def path(self) -> str: """The requested broadcast path.""" return self._inner.path() - def prepare(self) -> BroadcastPrepared: - """Start answering as a new stream under a fresh instance, hidden until published.""" - return BroadcastPrepared(self._inner.prepare()) + def route(self, *, hidden: bool = False, cost: int = 0, instance: str | None = None, epoch: int = 0) -> Route: + """Answer with the path's own exact :class:`Route`, owning a new broadcast. + + The route serves a fresh instance unless ``instance`` names one, so a job that + restarts is a new stream. Created visible, it announces now and answers the waiting + requesters; created ``hidden``, they wait until :meth:`Route.announce`, so the job can + fill its catalog first, and cancelling the route before then refuses them. Ending the + route withdraws only this path. + """ + return Route(self._inner.route(_options(hidden=hidden, cost=cost, instance=instance, epoch=epoch))) def serve(self, broadcast: BroadcastConsumer) -> None: """Serve held content under the prefix route's continuous sequence space, without an exact route.""" @@ -127,72 +136,75 @@ def reject(self, error_code: int) -> None: self._inner.reject(error_code) -class BroadcastPrepared: - """A claim answer being filled before its exact route is announced.""" - - def __init__(self, inner: MoqBroadcastPrepared) -> None: - self._inner = inner - self._broadcast = BroadcastProducer._from_inner(inner.broadcast()) - - @property - def broadcast(self) -> BroadcastProducer: - """The unannounced broadcast to fill before publishing; only `publish` announces it.""" - return self._broadcast - - def publish(self) -> Publication: - """Announce the filled broadcast and resolve waiting requesters.""" - return Publication(self._inner.publish(), self._broadcast) +class Route(_Stream[BroadcastRequest]): + """A route on an origin: an exact route owning one broadcast, or a prefix route + yielding the requests beneath it. - -class Publication: - """A broadcast published on an origin: the broadcast to fill and its announcement. - - Dropping it does not retract the route; :meth:`BroadcastProducer.close` does. + Hold it for as long as the route should stay advertised: dropping or cancelling it + retracts it, as does closing an exact route's broadcast. A broadcast handle alone does + not keep it announced. Iterate a prefix route with ``async for`` for its + :class:`BroadcastRequest` values; usable as an async context manager that cancels the + route on exit. """ - def __init__(self, inner: MoqPublication, broadcast: BroadcastProducer) -> None: + def __init__(self, inner: MoqRoute) -> None: self._inner = inner - self._broadcast = broadcast + self._broadcast: BroadcastProducer | None = None @property def broadcast(self) -> BroadcastProducer: - """The broadcast to fill, without announcement control.""" + """The broadcast this exact route owns, to fill with tracks. + + Raises ``moq.Error.Internal`` on a prefix route, which owns none: answer its requests instead. + """ + if self._broadcast is None: + self._broadcast = BroadcastProducer._from_inner(self._inner.broadcast()) return self._broadcast - def announce(self, route: AnnounceRoute | None = None) -> None: - """Advertise the broadcast's exact path as a route, or re-price it in place. + @property + def instance(self) -> str: + """The stream this route serves, minted at creation unless one was named, and kept + across :meth:`withdraw` and :meth:`announce`.""" + return self._inner.instance_id() + + def announce(self) -> None: + """Make the route visible, or keep it so. - Until announced, the broadcast is invisible and unroutable for local - consumers and peers alike. Raises ``moq.Error.Closed`` once the broadcast closed. + A route from :meth:`BroadcastRequest.route` also answers the requesters waiting on + its path. Raises ``moq.Error.Closed`` once its broadcast closed. """ - self._inner.announce(route if route is not None else AnnounceRoute()) + self._inner.announce() - def unannounce(self) -> None: - """Retract the advertisement, if any, keeping the filled tracks alive. + def withdraw(self) -> None: + """Hide the route from everyone, keeping its broadcast and instance. - Announcing again brings it back. Raises ``moq.Error.Closed`` once the broadcast closed. + :meth:`announce` brings the same stream back; tracks already in flight carry on. """ - self._inner.unannounce() - + self._inner.withdraw() -class OriginRequests(_Stream[BroadcastRequest]): - """A served route: advertises a prefix and yields requests beneath it. + def set_cost(self, cost: int) -> None: + """Re-price the route in place: lower wins among routes covering the same prefix. - Usable as an async context manager that cancels the route on exit. - """ + A hidden route keeps the price for when it next announces. Raises + ``moq.Error.Closed`` once its broadcast closed. + """ + self._inner.set_cost(cost) - def __init__(self, inner: MoqOriginRequests) -> None: - self._inner = inner + async def _next(self) -> BroadcastRequest | None: + return await self.requested() - async def _next(self) -> BroadcastRequest: - return await self.requested_broadcast() + async def requested(self) -> BroadcastRequest | None: + """Await the next broadcast a consumer requests beneath this prefix route. - async def requested_broadcast(self) -> BroadcastRequest: - """Await the next broadcast a consumer requested but that isn't published yet.""" - return BroadcastRequest(await self._inner.requested_broadcast()) + Serve, route, or reject it; the requester stays pending until then. Returns + ``None`` once the origin closes, and at once on an exact route. + """ + request = await self._inner.requested() + return None if request is None else BroadcastRequest(request) def cancel(self) -> None: - """Stop serving and retract the route.""" + """Retract the route and release it now. An exact route's broadcast lives on until + :meth:`BroadcastProducer.close`.""" self._inner.cancel() @@ -238,12 +250,11 @@ async def request(self, path: str, *, instance: str | None = None) -> BroadcastC class OriginProducer: - """The publishing side of an origin: announce broadcasts for consumers to discover. + """The publishing side of an origin: route broadcasts for consumers to discover. - Call :meth:`create_broadcast` to publish at a path, :meth:`consume` for a - matching :class:`OriginConsumer`, or :meth:`requests` to advertise a prefix - and serve on-demand requests. Create, :meth:`requests` if tracks are served - on demand, populate, then :meth:`Publication.announce`. + Call :meth:`route` to publish a broadcast at a path, :meth:`route_prefix` to + serve on-demand requests beneath a prefix, or :meth:`consume` for a matching + :class:`OriginConsumer`. """ def __init__(self, *, cache_capacity_bytes: int | None = None) -> None: @@ -260,25 +271,29 @@ def consume(self) -> OriginConsumer: """Create a consumer that discovers the broadcasts this origin publishes.""" return OriginConsumer(self._inner.consume()) - def requests(self, prefix: str) -> OriginRequests: - """Advertise ``prefix`` and serve the requests beneath it. - - A route claims ``prefix`` and every path beneath it (``""`` claims every - path). A service that only serves some of them rejects the rest as they - are requested. Hold the returned handle while the route should stay - advertised. + def route( + self, path: str, *, hidden: bool = False, cost: int = 0, instance: str | None = None, epoch: int = 0 + ) -> Route: + """Create a :class:`Route` at exactly ``path``, owning a new broadcast to fill. + + Visible at once unless ``hidden``: a hidden route is invisible and unroutable, for + this origin's consumers and peers alike, until :meth:`Route.announce`, so create it + hidden to fill the catalog first. ``cost`` prices it: lower wins. The route serves a + fresh instance unless ``instance`` names a stable one, whose runs raise ``epoch``. + Hold the route: dropping or cancelling it retracts it, and + :meth:`BroadcastProducer.close` ends both. """ - return OriginRequests(self._inner.requests(prefix)) + return Route(self._inner.route(path, _options(hidden=hidden, cost=cost, instance=instance, epoch=epoch))) - def create_broadcast(self, path: str) -> Publication: - """Create a broadcast at ``path``, returning its :class:`Publication`. + def route_prefix( + self, prefix: str, *, hidden: bool = False, cost: int = 0, instance: str | None = None, epoch: int = 0 + ) -> Route: + """Create a :class:`Route` over ``prefix`` that yields the requests beneath it. - Fill :attr:`Publication.broadcast`. The broadcast is invisible and - unroutable, for this origin's consumers and peers alike, until - :meth:`Publication.announce`. Announce it after populating tracks. Create, - :meth:`requests` if tracks are served on demand, populate, then announce. - :meth:`BroadcastProducer.close` ends it for good; dropping its last - handle, the publication included, does the same. + A route claims ``prefix`` and every path beneath it (``""`` claims every + path). A service that only serves some of them rejects the rest as they + are requested. Hold the route while it should stay advertised. """ - inner = self._inner.create_broadcast(path) - return Publication(inner, BroadcastProducer._from_inner(inner.broadcast())) + return Route( + self._inner.route_prefix(prefix, _options(hidden=hidden, cost=cost, instance=instance, epoch=epoch)) + ) diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index ed555cfe651..96cc160a038 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -318,9 +318,9 @@ def cancel(self) -> None: class BroadcastProducer: """Wraps MoqBroadcastProducer with a cleaner interface. - It fills tracks; announcing belongs to the :class:`moq.Publication` that - :meth:`moq.OriginProducer.create_broadcast` returns, the way to publish at a - path. Constructing one directly creates a standalone broadcast for local pub/sub. + It fills tracks; announcing belongs to the :class:`moq.Route` that + :meth:`moq.OriginProducer.route` returns, the way to publish at a path. + Constructing one directly creates a standalone broadcast for local pub/sub. """ def __init__(self) -> None: diff --git a/py/moq-rs/moq/server.py b/py/moq-rs/moq/server.py index 5a81fa4571d..ffde0e4740f 100644 --- a/py/moq-rs/moq/server.py +++ b/py/moq-rs/moq/server.py @@ -8,7 +8,7 @@ from moq_ffi import MoqQuicConfig, MoqRequest, MoqServer, MoqServerConfig, MoqServerTls, MoqTransport from ._records import _implementation, _strs -from .origin import OriginProducer, Publication +from .origin import OriginProducer, Route from .session import Session # The network transport carrying an incoming session. @@ -94,8 +94,7 @@ class Server: In simple mode (no origin provided), creates an internal origin automatically:: async with Server("127.0.0.1:4443", tls_generate=["localhost"]) as server: - publication = server.create_broadcast("live") - publication.announce() # unannounced broadcasts are invisible + route = server.route("live") # announced while held await server.serve() Or hand-roll the accept loop if you need per-request control:: @@ -205,15 +204,18 @@ async def __anext__(self) -> Request: raise StopAsyncIteration return Request(request) - def create_broadcast(self, path: str) -> Publication: - """Create a live broadcast at ``path``, served to incoming sessions. + def route( + self, path: str, *, hidden: bool = False, cost: int = 0, instance: str | None = None, epoch: int = 0 + ) -> Route: + """Create a route at ``path`` owning a broadcast served to incoming sessions; hold it + to keep it announced. - See :meth:`OriginProducer.create_broadcast`. + See :meth:`OriginProducer.route`. """ origin = self._publish_origin if origin is None: raise RuntimeError("no publish origin configured") - return origin.create_broadcast(path) + return origin.route(path, hidden=hidden, cost=cost, instance=instance, epoch=epoch) async def serve(self) -> None: """Accept every session in a loop, holding each one alive until it closes. diff --git a/py/moq-rs/moq/types.py b/py/moq-rs/moq/types.py index 26300416244..c38e9670646 100644 --- a/py/moq-rs/moq/types.py +++ b/py/moq-rs/moq/types.py @@ -4,9 +4,6 @@ timestamp, are owned in `_records` instead. """ -from moq_ffi import ( - MoqAnnounceRoute as AnnounceRoute, -) from moq_ffi import ( MoqAudioCodec as AudioCodec, ) @@ -45,7 +42,7 @@ MoqRateTarget as RateTarget, ) from moq_ffi import ( - MoqRoute as Route, + MoqRouteInfo as RouteInfo, ) from moq_ffi import ( MoqVideoCodec as VideoCodec, @@ -85,7 +82,6 @@ ) __all__ = [ - "AnnounceRoute", "Anchor", "AudioCodec", "AudioEncoderInput", @@ -109,7 +105,7 @@ "QuicConfig", "Range", "RateTarget", - "Route", + "RouteInfo", "Subscription", "Timestamp", "TrackInfo", diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index b84605c5297..6d0c672b8b5 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -21,12 +21,6 @@ async def until_wanted(demand: moq.TrackDemand, wanted: bool = True) -> None: pass -def create_announced(origin: moq.OriginProducer, path: str) -> moq.BroadcastProducer: - publication = origin.create_broadcast(path) - publication.announce() - return publication.broadcast - - async def routes(announced: moq.AnnounceConsumer): """Yield each route that makes its path present, skipping absences.""" async for event in announced: @@ -231,7 +225,8 @@ def test_audio_rejects_bad_init_bytes(): async def test_local_publish_consume_audio(): origin = moq.OriginProducer() - broadcast = create_announced(origin, "live") + route = origin.route("live") + broadcast = route.broadcast media = moq.media.TrackProducer.audio( broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=opus_head()) ) @@ -269,7 +264,8 @@ async def test_local_publish_consume_audio(): async def test_video_publish_consume(): origin = moq.OriginProducer() - broadcast = create_announced(origin, "video-test") + route = origin.route("video-test") + broadcast = route.broadcast media = moq.media.TrackProducer.video( broadcast, moq.media.VideoInit(format=moq.media.VideoFormat.AVC3, data=h264_init()) ) @@ -306,7 +302,8 @@ async def test_video_publish_consume(): async def test_video_publish_named_track(): origin = moq.OriginProducer() - broadcast = create_announced(origin, "video-named-test") + route = origin.route("video-named-test") + broadcast = route.broadcast media = moq.media.TrackProducer.video( broadcast, moq.media.VideoInit(format=moq.media.VideoFormat.AVC3, data=h264_init()), @@ -325,7 +322,8 @@ async def test_video_publish_named_track(): async def test_multiple_frames_ordering(): origin = moq.OriginProducer() - broadcast = create_announced(origin, "ordering-test") + route = origin.route("ordering-test") + broadcast = route.broadcast media = moq.media.TrackProducer.audio( broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=opus_head()) ) @@ -355,7 +353,8 @@ async def test_multiple_frames_ordering(): async def test_catalog_update_on_new_track(): origin = moq.OriginProducer() - broadcast = create_announced(origin, "catalog-update") + route = origin.route("catalog-update") + broadcast = route.broadcast _media1 = moq.media.TrackProducer.audio( broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=opus_head()) ) @@ -397,7 +396,7 @@ def test_close_twice_is_a_noop(): async def test_announced_broadcast(): origin = moq.OriginProducer() - _broadcast = create_announced(origin, "test/broadcast") + _route = origin.route("test/broadcast") consumer = origin.consume() @@ -413,51 +412,53 @@ async def test_following_restarts_on_a_new_instance(): consumer = origin.consume() announced = consumer.announced() following = consumer.follow("instance") - publication = origin.create_broadcast("instance") - # The broadcast mints its own instance and keeps it across re-announcing. - publication.announce() + # The route mints its own instance and keeps it across re-pricing. + first = origin.route("instance") present = await next_route(announced) assert isinstance(present, moq.AnnounceEventPresent) minted = present.announce.route.instance - assert minted + assert minted == first.instance assert await asyncio.wait_for(following.available(), timeout=5.0) is not None - # Another instance is another stream: followers restart onto it, while the path - # stays present, so neither the re-price nor the restart is listed. - publication.announce(moq.AnnounceRoute(cost=1)) - publication.announce(moq.AnnounceRoute(instance="cam", epoch=1)) + # Another route is another stream: followers restart onto it, while the path stays + # present, so neither the re-price nor the restart is listed. + first.set_cost(1) + second = origin.route("instance", instance="cam", epoch=1) + assert second.instance == "cam" assert await asyncio.wait_for(following.available(), timeout=5.0) is not None - publication.unannounce() + first.withdraw() + second.withdraw() absent = await next_route(announced) assert isinstance(absent, moq.AnnounceEventAbsent) assert absent.announce.route.instance == "cam" with pytest.raises(moq.Error.InvalidInstance): - publication.announce(moq.AnnounceRoute(instance="")) + origin.route("refused", instance="") following.cancel() - publication.broadcast.close() + first.broadcast.close() + second.broadcast.close() async def test_following_reports_the_path_offline_until_it_returns(): origin = moq.OriginProducer() consumer = origin.consume() - publication = origin.create_broadcast("live") - publication.announce() + route = origin.route("live") async with consumer.follow("live") as following: assert await asyncio.wait_for(following.available(), timeout=5.0) is not None - publication.unannounce() + route.withdraw() assert await asyncio.wait_for(following.available(), timeout=5.0) is None - publication.announce() + route.announce() assert await asyncio.wait_for(following.available(), timeout=5.0) is not None - publication.broadcast.close() + route.broadcast.close() async def test_finish_serves_until_closed(): origin = moq.OriginProducer() consumer = origin.consume() announced = consumer.announced() - broadcast = create_announced(origin, "finish") + route = origin.route("finish") + broadcast = route.broadcast assert isinstance(await next_route(announced), moq.AnnounceEventPresent) track = broadcast.publish_track("status") @@ -814,18 +815,20 @@ async def test_dynamic_track_request_can_publish_media(): async def test_dynamic_broadcast_request(): origin = moq.OriginProducer(cache_capacity_bytes=4096) - dynamic = origin.requests("") + dynamic = origin.route_prefix("") consumer = origin.consume() requesting = asyncio.create_task(consumer.request("dynamic/broadcast")) - request = await asyncio.wait_for(dynamic.requested_broadcast(), timeout=5.0) + request = await asyncio.wait_for(dynamic.requested(), timeout=5.0) + assert request is not None assert request.path == "dynamic/broadcast" - prepared = request.prepare() - track = prepared.broadcast.publish_track("status", moq.TrackInfo(timescale=1_000_000)) - served = prepared.publish() - assert served.broadcast is prepared.broadcast + # A hidden job route answers once it announces, under its own instance. + served = request.route(hidden=True) + assert served.instance != dynamic.instance + track = served.broadcast.publish_track("status", moq.TrackInfo(timescale=1_000_000)) + served.announce() with pytest.raises(Exception): _ = request.path @@ -844,12 +847,13 @@ async def test_dynamic_broadcast_request(): async def test_dynamic_serves_held_content_without_an_exact_route(): origin = moq.OriginProducer() - dynamic = origin.requests("live") + dynamic = origin.route_prefix("live") held = moq.BroadcastProducer() track = held.publish_track("status", moq.TrackInfo(timescale=1_000_000)) source = held.consume() requesting = asyncio.create_task(origin.consume().request("live/cam")) - request = await dynamic.requested_broadcast() + request = await dynamic.requested() + assert request is not None request.serve(source) with pytest.raises(Exception): request.serve(source) @@ -865,11 +869,12 @@ async def test_dynamic_serves_held_content_without_an_exact_route(): async def test_dynamic_broadcast_request_can_reject(): origin = moq.OriginProducer() - dynamic = origin.requests("") + dynamic = origin.route_prefix("") consumer = origin.consume() requesting = asyncio.create_task(consumer.request("missing")) - request = await asyncio.wait_for(dynamic.requested_broadcast(), timeout=5.0) + request = await asyncio.wait_for(dynamic.requested(), timeout=5.0) + assert request is not None assert request.path == "missing" request.reject(404) @@ -1013,7 +1018,8 @@ async def test_container_consumer_default_latency_and_context_manager(): """TrackConsumer.subscribe defaults the latency; the returned consumer is also an async context manager.""" origin = moq.OriginProducer() - broadcast = create_announced(origin, "live") + route = origin.route("live") + broadcast = route.broadcast media = moq.media.TrackProducer.audio( broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=opus_head()) ) @@ -1040,7 +1046,8 @@ async def test_container_consumer_default_latency_and_context_manager(): async def test_raw_publish_consume(): origin = moq.OriginProducer() - broadcast = create_announced(origin, "robot/arm") + route = origin.route("robot/arm") + broadcast = route.broadcast raw = broadcast.publish_track("events") consumer = origin.consume() @@ -1065,7 +1072,8 @@ async def test_raw_publish_consume(): async def test_raw_multiple_frames(): origin = moq.OriginProducer() - broadcast = create_announced(origin, "robot/io") + route = origin.route("robot/io") + broadcast = route.broadcast raw = broadcast.publish_track("commands", moq.TrackInfo(max_age=None)) consumer = origin.consume() @@ -1194,7 +1202,8 @@ async def test_broadcast_producer_consume_direct(): async def test_raw_group_sequence(): """Consumer sees the same sequence numbers the producer assigned.""" origin = moq.OriginProducer() - broadcast = create_announced(origin, "track/seq") + route = origin.route("track/seq") + broadcast = route.broadcast raw = broadcast.publish_track("seq", moq.TrackInfo(max_age=None, timescale=1_000_000)) consumer = origin.consume() @@ -1231,7 +1240,8 @@ async def test_default_iteration_is_sequence_order(): this fails if the default iteration ever reverts to recv_group. """ origin = moq.OriginProducer() - broadcast = create_announced(origin, "track/ordering") + route = origin.route("track/ordering") + broadcast = route.broadcast raw = broadcast.publish_track("ordering", moq.TrackInfo(max_age=None)) subscription = moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=FROM_GROUP_0) @@ -1356,7 +1366,8 @@ async def test_container_group_fails_loudly(): async def test_raw_multi_frame_group(): """A single group can carry multiple frames, not just one per group.""" origin = moq.OriginProducer() - broadcast = create_announced(origin, "stream/chunks") + route = origin.route("stream/chunks") + broadcast = route.broadcast raw = broadcast.publish_track("chunks") consumer = origin.consume() @@ -1586,7 +1597,8 @@ def test_encode_audio_with_opus_object(): async def test_audio_consumer_reports_its_playout_delay(): """A fixed playout delay is reported back as is; an estimated one moves as frames are read.""" origin = moq.OriginProducer() - broadcast = create_announced(origin, "audio-delay") + route = origin.route("audio-delay") + broadcast = route.broadcast audio = moq.audio.Producer( moq.media.CatalogProducer(broadcast), moq.AudioEncoderInput(format=moq.AudioSampleFormat.F32, sample_rate=48_000, channels=1), @@ -1630,7 +1642,8 @@ def output(delay: timedelta | None) -> moq.audio.DecoderOutput: async def test_decode_video_frame(): """A decoded frame owns its picture and converts to either layout, even after its consumer is cancelled.""" origin = moq.OriginProducer() - broadcast = create_announced(origin, "video-decode-frame") + route = origin.route("video-decode-frame") + broadcast = route.broadcast video = moq.video.Producer( moq.media.CatalogProducer(broadcast), moq.VideoEncoderInput( @@ -1686,39 +1699,39 @@ async def test_decode_video_frame(): async def test_broadcast_is_reachable_only_while_announced(): origin = moq.OriginProducer() - publication = origin.create_broadcast("live") - track = publication.broadcast.publish_track("events") + route = origin.route("live", hidden=True) + track = route.broadcast.publish_track("events") consumer = origin.consume() with pytest.raises(Exception): await asyncio.wait_for(consumer.request("live"), timeout=5.0) - publication.announce() + route.announce() announced = consumer.announced() first = await next_route(announced) assert isinstance(first, moq.AnnounceEventPresent) assert first.announce.prefix == "live" - publication.unannounce() + route.withdraw() retracted = await next_route(announced) assert isinstance(retracted, moq.AnnounceEventAbsent) assert retracted.announce.prefix == "live" with pytest.raises(Exception): await asyncio.wait_for(consumer.request("live"), timeout=5.0) - publication.announce() + route.announce() back = await next_route(announced) assert isinstance(back, moq.AnnounceEventPresent) + assert back.announce.route.instance == route.instance await asyncio.wait_for(consumer.request("live"), timeout=5.0) announced.cancel() track.finish() - publication.broadcast.close() + route.broadcast.close() async def test_an_instance_pins_request_and_follow(): origin = moq.OriginProducer() consumer = origin.consume() - publication = origin.create_broadcast("live") - publication.announce(moq.AnnounceRoute(instance="cam")) + route = origin.route("live", instance="cam") await asyncio.wait_for(consumer.request("live", instance="cam"), timeout=5.0) with pytest.raises(moq.Error.Protocol): @@ -1728,39 +1741,53 @@ async def test_an_instance_pins_request_and_follow(): async with consumer.follow("live", instance="cam") as following: assert await asyncio.wait_for(following.available(), timeout=5.0) is not None # Another instance taking the path over ends the pinned stream. - publication.announce(moq.AnnounceRoute(instance="other")) + other = origin.route("live", instance="other") assert await asyncio.wait_for(following.available(), timeout=5.0) is None - publication.broadcast.close() + other.broadcast.close() + route.broadcast.close() -async def test_dropping_a_publication_keeps_its_route(): +async def test_the_route_keeps_its_broadcast_announced(): origin = moq.OriginProducer() consumer = origin.consume() - publication = origin.create_broadcast("live") - broadcast = publication.broadcast - assert publication.broadcast is broadcast - publication.announce() - del publication + route = origin.route("live") + broadcast = route.broadcast + assert route.broadcast is broadcast + # The broadcast handle alone retracts nothing. + del broadcast await asyncio.wait_for(consumer.request("live"), timeout=5.0) - broadcast.close() + # Dropping the route retracts it; its broadcast lives on for its other handles. + broadcast = route.broadcast + del route with pytest.raises(moq.Error.Protocol): await asyncio.wait_for(consumer.request("live"), timeout=5.0) + broadcast.publish_track("data") + broadcast.close() + + # Cancelling retracts it too, and later calls fail. + cancelled = origin.route("cancelled") + await asyncio.wait_for(consumer.request("cancelled"), timeout=5.0) + cancelled.cancel() + with pytest.raises(moq.Error.Protocol): + await asyncio.wait_for(consumer.request("cancelled"), timeout=5.0) + with pytest.raises(moq.Error.Cancelled): + cancelled.announce() + cancelled.broadcast.close() -async def test_a_stale_publication_leaves_its_replacement_alone(): +async def test_a_closed_route_leaves_its_replacement_alone(): origin = moq.OriginProducer() consumer = origin.consume() - stale = origin.create_broadcast("live") - stale.announce() + stale = origin.route("live") stale.broadcast.close() - replacement = origin.create_broadcast("live") - replacement.announce() + replacement = origin.route("live") with pytest.raises(moq.Error.Closed): stale.announce() with pytest.raises(moq.Error.Closed): - stale.unannounce() + stale.set_cost(1) + stale.withdraw() await asyncio.wait_for(consumer.request("live"), timeout=5.0) replacement.broadcast.close() @@ -1771,10 +1798,10 @@ async def test_announced_pattern_captures(): announced = consumer.announced("room", filter="*/chat") # A claim at "room" could serve a match, but its own name is none, so it is not listed. - dynamic = origin.requests("room") + dynamic = origin.route_prefix("room") - audio = create_announced(origin, "room/alice/audio") - chat = create_announced(origin, "room/alice/chat") + audio = origin.route("room/alice/audio") + chat = origin.route("room/alice/chat") match = await next_route(announced) assert isinstance(match, moq.AnnounceEventPresent) assert match.announce.prefix == "room/alice/chat" @@ -1782,19 +1809,21 @@ async def test_announced_pattern_captures(): announced.cancel() dynamic.cancel() - audio.close() - chat.close() + audio.broadcast.close() + chat.broadcast.close() async def test_dynamic_serves_a_request_under_a_prefix(): origin = moq.OriginProducer() - dynamic = origin.requests("live") + dynamic = origin.route_prefix("live") consumer = origin.consume() + with pytest.raises(moq.Error.Internal): + _ = dynamic.broadcast pending = asyncio.create_task(consumer.request("live/cam")) - request = await asyncio.wait_for(dynamic.requested_broadcast(), timeout=5.0) + request = await asyncio.wait_for(anext(dynamic), timeout=5.0) assert request.path == "live/cam" - served = request.prepare().publish() + served = request.route() await asyncio.wait_for(pending, timeout=5.0) dynamic.cancel() served.broadcast.close() @@ -1809,9 +1838,9 @@ async def assert_cancelled(awaitable) -> None: assert moq.is_shutdown(excinfo.value) origin = moq.OriginProducer() - async with origin.requests("live") as origin_dynamic: + async with origin.route_prefix("live") as origin_dynamic: pass - await assert_cancelled(origin_dynamic.requested_broadcast()) + await assert_cancelled(origin_dynamic.requested()) broadcast = moq.BroadcastProducer() async with broadcast.requests() as broadcast_dynamic: diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index 076906ff84b..6b9376e30ae 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -38,12 +38,12 @@ async def test_server_client_roundtrip(): """Server publishes a broadcast; a client connects and receives a frame.""" async with moq.Server("127.0.0.1:0", versions=["moq-lite-07-wip"], tls_generate=["localhost"]) as server: # Publish a broadcast on the server side. - publication = server.create_broadcast("hello") - broadcast = publication.broadcast + published = server.route("hello", hidden=True) + broadcast = published.broadcast media = moq.media.TrackProducer.audio( broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=opus_head()) ) - publication.announce() + published.announce() # Auto-accept incoming sessions in the background so the handshake # completes from the server side. Hold references so the sessions @@ -158,9 +158,8 @@ async def accept_loop() -> None: assert session.state().failure is None # A broadcast published only after the reconnect still arrives. - publication = server.create_broadcast("after-reconnect") - broadcast = publication.broadcast - publication.announce() + published = server.route("after-reconnect") + broadcast = published.broadcast async for announcement in routes(client.announced()): assert announcement.prefix == "after-reconnect" break @@ -422,9 +421,8 @@ async def accept_once() -> None: async def test_serve_helper_accepts_clients(): """Server.serve() accepts incoming sessions and holds them automatically.""" async with moq.Server("127.0.0.1:0", tls_generate=["localhost"]) as server: - publication = server.create_broadcast("via-serve") - broadcast = publication.broadcast - publication.announce() + published = server.route("via-serve") + broadcast = published.broadcast serve_task = asyncio.create_task(server.serve()) try: @@ -448,9 +446,8 @@ async def test_serve_helper_accepts_clients(): async def test_broadcast_route_over_wire(): """A route received over the wire exposes its hop chain and cost.""" async with moq.Server("127.0.0.1:0", tls_generate=["localhost"]) as server: - publication = server.create_broadcast("with-route") - broadcast = publication.broadcast - publication.announce() + published = server.route("with-route") + broadcast = published.broadcast serve_task = asyncio.create_task(server.serve()) try: @@ -507,9 +504,8 @@ async def drain(reader: moq.TrackConsumer) -> None: # rather than lean on the last session reference dropping. session = client.session assert session is not None - publication = client.create_broadcast("live") - broadcast = publication.broadcast - publication.announce() + published = client.route("live") + broadcast = published.broadcast track = broadcast.publish_track("data") await asyncio.wait_for(accepted.wait(), timeout=5.0) consume = sessions[0].consume() diff --git a/py/moq-rs/tests/test_testing_clock.py b/py/moq-rs/tests/test_testing_clock.py index a0b3e23f5a4..e5ee9450619 100644 --- a/py/moq-rs/tests/test_testing_clock.py +++ b/py/moq-rs/tests/test_testing_clock.py @@ -25,7 +25,8 @@ def test_a_pending_timer_waits_for_advance() -> None: async def main(): # The origin's driver runs the timers that judge a group stale. origin = moq.OriginProducer() - track = origin.create_broadcast("clock").broadcast.publish_track("track", moq.TrackInfo(max_age=None)) + route = origin.route("clock", hidden=True) + track = route.broadcast.publish_track("track", moq.TrackInfo(max_age=None)) from_group_0 = [moq.Range(start=moq.Anchor.ABSOLUTE(group=0))] consumer = track.consume(moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=from_group_0)) diff --git a/quest/m1/announce-takeover.md b/quest/m1/announce-takeover.md index c97f34a3699..91719dd6e23 100644 --- a/quest/m1/announce-takeover.md +++ b/quest/m1/announce-takeover.md @@ -59,8 +59,8 @@ this quest removes the predecessor machinery and grows to [XL]. `doc/concept/moq-lite.md`. - **Inheriting the instance.** Decided 2026-11-03 (maintainer, on [moq-dev/moq#7770](https://github.com/moq-dev/moq/pull/7770)): - `request.route(options)` from - [One Route handle](/quest/m1/api-audit/route/handle.md) mints a fresh + `request.route(options)`, from + [One Route handle](https://github.com/moq-dev/moq/pull/7806), mints a fresh instance by default, and ending a job leaves its prefix route open, with no history of ended paths. Carrying the prefix route's instance onto the path's exact route, so that the answer the waiting request gets is that @@ -146,10 +146,6 @@ Public API: breaking; removes `Takeover` and the predecessor fields in every language. Wire: removes lite-07's ANNOUNCE_TAKEOVER (0x5), adding nothing beyond [Instance and epoch](https://github.com/moq-dev/moq/pull/7489)'s fields. -## Required - -- [One Route handle](/quest/m1/api-audit/route/handle.md) - `request.route` creates the path's exact route, minting a fresh instance by default - ## Related - [Claim answer epochs](https://github.com/moq-dev/moq/pull/5678) - why a restarted job must never be stitched to its predecessor diff --git a/quest/m1/api-audit/route/README.md b/quest/m1/api-audit/route/README.md index 8a0b7c9c14c..d070f5b8149 100644 --- a/quest/m1/api-audit/route/README.md +++ b/quest/m1/api-audit/route/README.md @@ -167,7 +167,7 @@ stale, including `doc/concept/identity.md`. ## Required -- [One Route handle](/quest/m1/api-audit/route/handle.md) - `Publication`, `Prepared`, `Announcer` and `Requests` become one `Route` that owns its broadcast, with app options separate from transit facts +- [Transit facts stay read-only](/quest/m1/api-audit/route/facts.md) - `Hop`, `Hops` and `HopLimit` leave the public API, and JS `RouteInfo` hides epoch and auth ## Related diff --git a/quest/m1/api-audit/route/facts.md b/quest/m1/api-audit/route/facts.md new file mode 100644 index 00000000000..6d7e201d9ef --- /dev/null +++ b/quest/m1/api-audit/route/facts.md @@ -0,0 +1,42 @@ +# [L] Transit facts stay read-only + +## Goal + +Hops, via, source, the epoch and the anonymous mark are facts the origin and +the relays fill in, never something an application sets. `Hop`, `Hops` and +`HopLimit` leave the public API in Rust, JS and the bindings, and a received +announcement exposes its hop chain as plain ids. JS `RouteInfo` stops exposing +`epoch` and `auth`, as Rust's already does not. + +Non-goals: the route handle and its options, which +[One Route handle](https://github.com/moq-dev/moq/pull/7806) landed, and the +wire. + +## Plan + +Split from [One Route handle](https://github.com/moq-dev/moq/pull/7806), which +made `origin::RouteInfo` read-only (getters, no public builders) and moved app +settings to `RouteOptions`, but kept these types public because removing them +reaches every origin construction: + +- **Rust.** `origin::Config::new(Hop)` and `Config::hop` take a plain non-zero + id, `Config::max_hops` a plain count, and `Producer::hop()`/`Consumer::hop()` + return ids or go crate-private. `RouteInfo::hops()` returns ids rather than + `&Hops`. `moq_net::fuzz` keeps whatever benches and tests need to build relay + chains (`fuzz::route_info`, `fuzz::excluding`). About 100 test and bench + sites build a config with `Hop::new(..)`; moq-relay's cluster id and + moq-ffi/moq-c already pass plain ids. +- **JS.** Stop exporting `Hop`, `HopSchema` and `isAnonymous` from `@moq/net`'s + entry, keep `RouteInfo` to instance, cost, hops (as bigints) and anonymity, + and move `epoch` and `auth` to the internal wire view (`wireOf`) that + sessions already use. +- **Docs and MIGRATE.** `rs/moq-net/MIGRATE.md`, `js/net/MIGRATE.md` and + `doc/lib/rs/moq-net.md`. + +Run `just check`. + +Public API: breaking in moq-net and @moq/net. Wire: none. + +## Related + +- [Routes are the origin API](/quest/m1/api-audit/route/README.md) - the epic this finishes diff --git a/quest/m1/api-audit/route/handle.md b/quest/m1/api-audit/route/handle.md deleted file mode 100644 index d3ba60ceb48..00000000000 --- a/quest/m1/api-audit/route/handle.md +++ /dev/null @@ -1,126 +0,0 @@ -# [XL] One Route handle - -## Goal - -On the publishing side, ownership runs origin → route → broadcast → track → -group → frame. An application creates a `Route` on the origin, and the -route creates and owns its broadcast. `Publication`, `Prepared`, -`Announcer`, `Requests` and `Producer::publish` are gone, in Rust, JS, -moq-ffi, moq-c and the wrappers: - -```rust -// An exact route owns one broadcast; dropping the route withdraws it. -let route = origin.route("live/alice", Options::hidden())?; -route.broadcast().create_track("catalog", info)?; -route.announce(); // visible now, same instance -route.set_cost(5); // re-prices in place -route.withdraw(); // hidden; announce() again continues the same stream - -// A prefix route serves requests. -let claim = origin.route_prefix("transcode", Options::default())?; -while let Some(request) = claim.requested().await { - // Either serve a broadcast already held, under the claim's instance... - // request.serve(held); - // ...or create the path's own exact route. - let job = request.route(Options::default())?; - spawn(run(job)); -} -``` - -A `Route` mints its instance when it is created and keeps it for its -lifetime, across withdraw, re-announce and reconnects, because it owns the -same broadcast and its sequences continue. A new run is a new `Route`. Apps -pass only options: visibility at creation, `cost`, `auth`, and a stable -`instance` for a publisher that keeps its sequence space across restarts -(see [Instance and epoch](https://github.com/moq-dev/moq/pull/7489)). Setting -an instance grants no more than a minted one does: publishing still -requires the path's grant. A route exposes its own instance (`route.instance()`), so the OBS dock can -show it again. Hops, via, source and the anonymous mark become -read-only facts on a received announcement, and `Hop`, `Hops` and -`HopLimit` leave the public API. - -Non-goals: the instance model ([Instance and epoch](https://github.com/moq-dev/moq/pull/7489)), -announce events (a path listing plus `follow` since -[moq-dev/moq#7678](https://github.com/moq-dev/moq/pull/7678)), -the read side, which instance owns, and the route layer's wire metric -(`drafts/draft-lcurley-moq-lite.md`). - -## Plan - -Decided 2026-10-30 (maintainer); see the [epic](/quest/m1/api-audit/route/README.md). -The names above are a sketch. Settle the final ones in the PR, keeping Rust, -JS and the bindings identical. - -- **The route owns the broadcast.** `route.broadcast()` returns the - `broadcast::Producer` that the 18 library entry points already take - (`moq-mux` catalog and importers, `moq-hls` import, the `moq-rtc` codecs, - `moq-room` chat, `moq-boy` status). Today the broadcast holds its own - announcer (`rs/moq-net/src/model/broadcast.rs:252-292`, and - `js/net/src/broadcast.ts:391`). That inversion goes: the broadcast knows - nothing of routes, and `broadcast::Producer::announce`/`unannounce`/ - `route` are removed. A standalone `broadcast::Producer` stays for - in-process pipelines and tests. It can only be published through a - prefix route's `serve`, as today, where a standalone broadcast cannot be - announced. -- **Prefix routes.** A prefix route yields requests, and each one is - answered by `serve(consumer)`, - by `route(options)`, or by `reject`. `route(options)` creates the path's - exact `Route`. A prefix route takes cost and auth as an exact one does, - so claims can be priced. Today `Requests::route()` is always the default - and `update_route` is crate-private. -- **A job's instance.** ✅ Decided 2026-11-03 (maintainer, on - [moq-dev/moq#7770](https://github.com/moq-dev/moq/pull/7770)): - `request.route(options)` mints a fresh instance by default, as - `Request::prepare` does today, so a job that ends and restarts beneath - the same prefix gets a new instance for its restarted sequences. An - explicit stable instance in the options is only for a caller that - continues its sequences. Ending a job's route withdraws only that path: - the prefix route stays open and keeps answering later requests, each - with its own job lifetime, and the origin keeps no history of ended - paths. The existing predecessor handling stays until - [announce takeover](/quest/m1/announce-takeover.md) replaces it, and - that quest owns continuing the claim's readers on the job's route. - Rejected: inheriting the prefix route's instance by default and making - the prefix terminal once a materialized job ends, which would change - long-lived services; and inheriting it with automatic restarts, which - needs ended-path history or a retirement design this quest does not own. -- **Visibility, not unannounced broadcasts.** Callers that fill the catalog - first (`moq-cli` hls, rtsp and publish; moq-mux - `ts/programs.rs`) or announce after SDP (`moq-rtc/server/whip.rs`) create - the route hidden and announce it when ready. js/publish's on/off toggle - becomes withdraw and announce on one route, so viewers continue rather - than restart. -- **Sessions.** Relay forwarding keeps a crate-private construction with - forwarded instance, epoch, hops and cost, which the deleted - `requests_route` and `dynamic_route` did. `moq_net::fuzz`'s hatches - shrink to what tests still need. -- **JS leaks.** Removing `Requests`/`requestsRoute`/`updateRoute` also - removes their `@internal`-but-public exposure on `Table`. Stop exporting - `Epoch.toBytes`/`fromBytes`, `RequestSlot` and `RouteEntry`, and delete - the orphaned `@internal` doc blocks (`js/net/src/origin.ts:2160-2176`). -- **Bindings.** These all move to the route handle: - - moq-ffi's `MoqRoute`, `MoqPublication`, `MoqBroadcastRequest` and - `MoqBroadcastPrepared`. - - moq-c's `moq_origin_requests`, `moq_broadcast_request_*`, - `moq_broadcast_prepared_*`, `moq_publication_*` and `moq_mint_epoch`. - - The py, kt, swift, dart and go wrappers. - - moq-c's API gaps error-code fix applies to - whichever functions remain. -- **Callers.** Migrate every caller: about 25 crates use `create_broadcast` - or `publish`, about 19 set an epoch, plus `@moq/publish`, moq-boy, carla - and the e2ee generations. The rs/moq-net and js/net `MIGRATE.md` entries - and the PR's Impact section give the mapping, including moq.pro's - `.dash` claim and sync-ingest mirror. -- **Docs.** Update `doc/concept/identity.md`'s publishing and lazy-job - examples, `doc/lib/rs`, `doc/lib/js`, `doc/lib/c`, and each binding's - README. - -Run `just check` and `just test interop --all`. - -Public API: breaking across moq-net, @moq/net, moq-ffi, moq-c and the -wrappers. Wire: none. - -## Related - -- No constructible internal handles - the same JS hygiene rule diff --git a/quest/m1/cluster-routing/routes/session.md b/quest/m1/cluster-routing/routes/session.md index 34f60fc1e9e..fcbae7fba94 100644 --- a/quest/m1/cluster-routing/routes/session.md +++ b/quest/m1/cluster-routing/routes/session.md @@ -146,10 +146,6 @@ by a proven key, every remaining attack stays inside the forger's grant, with no grant field, no issuer-coordinated labels, and support for token-less admission. -## Required - -- [One Route handle](/quest/m1/api-audit/route/handle.md) - the origin's route surface this rewrites - ## Related - [Routes and announces](/quest/m1/cluster-routing/routes/README.md) - the contract diff --git a/rs/hang/examples/video.rs b/rs/hang/examples/video.rs index 899b59c8807..7910196fd66 100644 --- a/rs/hang/examples/video.rs +++ b/rs/hang/examples/video.rs @@ -82,11 +82,10 @@ fn create_track(broadcast: &mut moq_net::broadcast::Producer) -> anyhow::Result< async fn run_broadcast(origin: moq_net::origin::Producer) -> anyhow::Result<()> { // Create a broadcast on the origin and announce its path. // NOTE: The path is empty because we're using the URL to scope the broadcast. - let broadcast = origin.create_broadcast("").context("failed to create broadcast")?; - broadcast - .announce(Default::default()) + let route = origin + .route("", moq_net::origin::RouteOptions::default()) .context("failed to announce broadcast")?; - let track = create_track(&mut broadcast.broadcast().clone())?; + let track = create_track(&mut route.broadcast().clone())?; // Wrap in a Producer for keyframe-based group management. let mut producer = moq_mux::container::Producer::new( diff --git a/rs/moq-archive/README.md b/rs/moq-archive/README.md index b96bee472f7..da623fa263d 100644 --- a/rs/moq-archive/README.md +++ b/rs/moq-archive/README.md @@ -31,7 +31,7 @@ use moq_archive::object_store::memory::InMemory; let store = moq_archive::Store::new(InMemory::new(), "recordings/demo"); moq_archive::Producer::new(store.clone(), broadcast, Default::default()).run().await?; -// `served` is an `origin::Publication`'s fill, announced once `open` returns. +// `served` is an `origin::Route`'s broadcast, created hidden and announced once `open` returns. let consumer = moq_archive::Consumer::open(store, served, Default::default()).await?; consumer.run().await?; ``` diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 724bc9aed6b..f42deec3cbb 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -975,11 +975,14 @@ mod tests { #[tokio::test(start_paused = true)] async fn latest_skips_a_warm_copys_backlog() { let publisher = origin(1); - let broadcast = publisher.create_broadcast("bcast").unwrap(); + let broadcast = publisher + .route("bcast", moq_net::origin::RouteOptions::hidden()) + .unwrap(); let track = broadcast + .broadcast() .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) .unwrap(); - broadcast.announce(Default::default()).unwrap(); + broadcast.announce().unwrap(); let mut demand = track.demand(); let mut producer = moq_mux::container::Producer::new( track, @@ -1053,11 +1056,14 @@ mod tests { #[tokio::test(start_paused = true)] async fn latest_loses_no_group_the_publisher_bursts_before_its_first_frame() { let publisher = origin(1); - let broadcast = publisher.create_broadcast("bcast").unwrap(); + let broadcast = publisher + .route("bcast", moq_net::origin::RouteOptions::hidden()) + .unwrap(); let track = broadcast + .broadcast() .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) .unwrap(); - broadcast.announce(Default::default()).unwrap(); + broadcast.announce().unwrap(); let mut producer = moq_mux::container::Producer::new( track, moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Audio), diff --git a/rs/moq-audio/src/encode/capture.rs b/rs/moq-audio/src/encode/capture.rs index 23727f18165..847f7708a8d 100644 --- a/rs/moq-audio/src/encode/capture.rs +++ b/rs/moq-audio/src/encode/capture.rs @@ -874,8 +874,8 @@ mod tests { let (capture, samples) = capture::test_source(); let (origin, origin_driver) = moq_net::origin::Producer::new(Default::default()); tokio::spawn(moq_net::time::run(origin_driver)); - let publication = origin.create_broadcast("live").unwrap(); - publication.announce(Default::default()).unwrap(); + let publication = origin.route("live", moq_net::origin::RouteOptions::hidden()).unwrap(); + publication.announce().unwrap(); let mut broadcast = publication.broadcast().clone(); let catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); diff --git a/rs/moq-bench/src/connection.rs b/rs/moq-bench/src/connection.rs index 0707226ff22..a612ea23d8a 100644 --- a/rs/moq-bench/src/connection.rs +++ b/rs/moq-bench/src/connection.rs @@ -108,7 +108,7 @@ pub async fn run(ctx: Connection) { config.name() }; - let mut broadcasts = Vec::new(); + let mut routes = Vec::new(); let mut publishing = Vec::new(); let mut own = HashSet::new(); let mut tasks = JoinSet::new(); @@ -126,14 +126,14 @@ pub async fn run(ctx: Connection) { }; for (relative, path) in paths { - let broadcast = match publish.create_broadcast(&path) { - Ok(broadcast) => broadcast, + let route = match publish.route(&path, moq_net::origin::RouteOptions::hidden()) { + Ok(route) => route, Err(err) => { tracing::error!(connection, %err, "failed to create broadcast"); continue; } }; - let track = match broadcast.create_track( + let track = match route.broadcast().create_track( TRACK, moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MILLI) @@ -145,14 +145,14 @@ pub async fn run(ctx: Connection) { continue; } }; - if let Err(err) = broadcast.announce(Default::default()) { + if let Err(err) = route.announce() { tracing::error!(connection, %err, "failed to announce broadcast"); continue; } own.insert(relative); - // Hold the broadcast producer for the connection's lifetime so it stays - // published and advertised. - broadcasts.push(broadcast); + // Hold the route for the connection's lifetime so it stays published and + // advertised. + routes.push(route); let published = Published::new(stats.clone()); publishing.push(Arc::downgrade(&published)); @@ -991,22 +991,26 @@ mod tests { let origin = moq_tokio::origin::spawn(); // The relay-internal broadcast: announced, but with no bench data track. - let _internal = origin.create_broadcast(".stats/node/host").unwrap(); - _internal.announce(Default::default()).unwrap(); + let _internal = origin + .route(".stats/node/host", moq_net::origin::RouteOptions::default()) + .unwrap(); // Our own broadcast: in the namespace, but excluded via the `own` set // (paths relative to the namespace, matching the scoped announce consumer). - let _previous = origin.create_broadcast("bench/previous/0/0").unwrap(); - _previous.announce(Default::default()).unwrap(); + let _previous = origin + .route("bench/previous/0/0", moq_net::origin::RouteOptions::default()) + .unwrap(); - let _own = origin.create_broadcast("bench/current/9/9").unwrap(); - _own.announce(Default::default()).unwrap(); + let _own = origin + .route("bench/current/9/9", moq_net::origin::RouteOptions::default()) + .unwrap(); let own = HashSet::from(["9/9".to_string()]); // One legitimate peer under the bench namespace with a single finished group. - let peer = origin.create_broadcast("bench/current/0/0").unwrap(); - peer.announce(Default::default()).unwrap(); - let track = peer.create_track(TRACK, timed()).unwrap(); + let peer = origin + .route("bench/current/0/0", moq_net::origin::RouteOptions::default()) + .unwrap(); + let track = peer.broadcast().create_track(TRACK, timed()).unwrap(); let mut group = track.append_group().unwrap(); group .write_frame(moq_net::Timestamp::now(), Bytes::from_static(b"{}")) @@ -1036,9 +1040,10 @@ mod tests { stats.clone(), )); - let broadcast = origin.create_broadcast("bench/run/chat").unwrap(); - broadcast.announce(Default::default()).unwrap(); - let track = broadcast.create_track(TRACK, timed()).unwrap(); + let broadcast = origin + .route("bench/run/chat", moq_net::origin::RouteOptions::default()) + .unwrap(); + let track = broadcast.broadcast().create_track(TRACK, timed()).unwrap(); tokio::task::yield_now().await; let mut group = track.append_group().unwrap(); let header = serde_json::json!({ @@ -1055,7 +1060,7 @@ mod tests { task.await.unwrap().unwrap(); assert_eq!(stats.groups_recv.load(Ordering::Relaxed), 1); - broadcast.close(); + broadcast.broadcast().close(); } /// The relay fails a group it gave up on (`Error::Lagged` once a subscriber diff --git a/rs/moq-boy/src/input.rs b/rs/moq-boy/src/input.rs index e50d8612d8f..3b4696b4b8d 100644 --- a/rs/moq-boy/src/input.rs +++ b/rs/moq-boy/src/input.rs @@ -190,15 +190,16 @@ mod tests { } /// Publish a viewer with a live command track. - fn viewer(origin: &moq_net::origin::Producer) -> (moq_net::origin::Publication, moq_net::track::Producer) { - let broadcast = origin.create_broadcast("alice").unwrap(); + fn viewer(origin: &moq_net::origin::Producer) -> (moq_net::origin::Route, moq_net::track::Producer) { + let broadcast = origin.route("alice", moq_net::origin::RouteOptions::hidden()).unwrap(); let track = broadcast + .broadcast() .create_track( "command", moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), ) .unwrap(); - broadcast.announce(moq_net::origin::Route::default()).unwrap(); + broadcast.announce().unwrap(); (broadcast, track) } @@ -253,7 +254,7 @@ mod tests { send(&old_track, r#"{"type":"reset"}"#); assert!(matches!(rx.recv().await, Some(Command::Reset))); - old.unannounce(); + old.withdraw(); assert!(matches!(rx.recv().await, Some(Command::ViewerLeft { .. }))); let (_new, new_track) = viewer(&origin); kio::clock::sleep(Duration::from_secs(1)).await; @@ -281,8 +282,10 @@ mod tests { let consumer = origin.consume(); tokio::spawn(async move { handle_viewers(&consumer, &tx).await }); - let claim = origin.requests("alice").unwrap(); - kio::clock::timeout(Duration::from_secs(1), claim.requested_broadcast()) + let claim = origin + .route_prefix("alice", moq_net::origin::RouteOptions::default()) + .unwrap(); + kio::clock::timeout(Duration::from_secs(1), claim.requested()) .await .expect("never asked") .expect("the claim closed") diff --git a/rs/moq-boy/src/main.rs b/rs/moq-boy/src/main.rs index e56168d146e..227101ac80a 100644 --- a/rs/moq-boy/src/main.rs +++ b/rs/moq-boy/src/main.rs @@ -256,15 +256,11 @@ async fn run(config: &Config) -> Result<()> { let publish_origin = moq_tokio::origin::spawn(); let (broadcast_path, viewer_path) = config.paths(&name)?; - // Create the broadcast on the publish origin and announce its path. - let broadcast = publish_origin - .create_broadcast(&broadcast_path) - .context("failed to create broadcast")?; - let instance = moq_net::Instance::random(); - broadcast - .announce(moq_net::origin::Route::default().with_instance(instance.clone(), 0)) + // Announce the game session's route on the publish origin; it owns the broadcast. + let route = publish_origin + .route(&broadcast_path, moq_net::origin::RouteOptions::default()) .context("failed to announce broadcast")?; - tracing::info!(broadcast = %broadcast_path, %instance, "announced"); + tracing::info!(broadcast = %broadcast_path, instance = %route.instance(), "announced"); // Consume origin: viewer broadcasts under the viewer prefix. // JS publishes viewer feedback at "{viewer_prefix}/{name}/{viewerId}" @@ -282,16 +278,15 @@ async fn run(config: &Config) -> Result<()> { .connect(url); // Set up catalog and encoders. - let catalog = - moq_mux::catalog::Producer::new(&mut broadcast.broadcast().clone(), moq_mux::catalog::Config::default())?; - let video_encoder = video::VideoEncoder::spawn(broadcast.broadcast().clone(), catalog.clone()).await; + let catalog = moq_mux::catalog::Producer::new(&mut route.broadcast().clone(), moq_mux::catalog::Config::default())?; + let video_encoder = video::VideoEncoder::spawn(route.broadcast().clone(), catalog.clone()).await; - let audio_encoder = audio::AudioEncoder::new(broadcast.broadcast().clone(), catalog.clone(), 44100)?; + let audio_encoder = audio::AudioEncoder::new(route.broadcast().clone(), catalog.clone(), 44100)?; let video_track = video_encoder.demand.clone(); let audio_track = audio_encoder.demand(); - let status_publisher = status::StatusPublisher::new(&mut broadcast.broadcast().clone())?; + let status_publisher = status::StatusPublisher::new(&mut route.broadcast().clone())?; let session = Arc::new(Session { video_encoder, @@ -332,7 +327,7 @@ async fn run(config: &Config) -> Result<()> { }; // Close the broadcast now, even if the emulator thread still holds a clone. - broadcast.close(); + route.broadcast().close(); result } diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 38a3689fb19..4ea469fb3eb 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -26,6 +26,22 @@ Map `_START` to `_PRESENT` and `_END` to `_ABSENT`, and drop `_UPDATE` handling. `moq_origin_follow` takes a `moq_follow_callback`, `(void *user_data, moq_follow_event event, int32_t code)`, instead of a `moq_status_callback`. `MOQ_FOLLOW_EVENT_ONLINE` carries each broadcast handle (where a positive code did), `MOQ_FOLLOW_EVENT_OFFLINE` reports the path going offline (or, for a follow pinned to an instance, another instance taking it over) with code `0`, and `MOQ_FOLLOW_EVENT_END` is the terminal callback, with `0` or a negative error that `moq_error()` explains (where a code `<= 0` was). Release `user_data` on `MOQ_FOLLOW_EVENT_END`. +### Publishing goes through one route handle + +A route handle replaces the publication, the prepared answer, and the request handler: + +- `moq_origin_create_broadcast(origin, path, len, &broadcast)` is `moq_origin_route(origin, path, len, options)`, which returns a route; `moq_route_broadcast(route)` gives the broadcast handle to fill. +- `moq_publication_announce(publication, route)` is `moq_route_announce(route)`, and re-pricing is `moq_route_set_cost(route, cost)`. `moq_publication_unannounce` is `moq_route_withdraw`, and `moq_publication_free` is `moq_route_free`. +- `moq_origin_requests(origin, prefix, len, on_request, user_data)` is `moq_origin_route_prefix(origin, prefix, len, options, on_request, user_data)`, and `moq_origin_requests_cancel` is `moq_route_free`. +- `moq_broadcast_request_prepare(request, &broadcast)` then `moq_broadcast_prepared_publish` is `moq_broadcast_request_route(request, options)`: create it hidden to fill it first, then `moq_route_announce`. `moq_broadcast_prepared_free` is `moq_route_free`. +- `moq_route_instance(route, &dst)` reads the stream's instance, minted at creation and kept across withdraw and announce. + +`moq_announce_route` is `moq_route_options`, given once at creation, and gains a trailing `hidden`. A zeroed or NULL `moq_route_options` is visible at once, so set `hidden` and call `moq_route_announce` after filling the catalog to keep the old create-then-announce order. A stable `instance` is fixed for the route's lifetime: announcing another one is a new route. + +Hold the route for as long as the broadcast should stay announced. `moq_route_free` now retracts it, while `moq_publish_close` still ends both; the broadcast handle alone no longer keeps it announced. + +`moq_route`, the struct carried by `moq_announce_event.route`, is renamed `moq_route_info`; its fields are unchanged. Recompile against the regenerated `moq.h`. + ### Separate datagram tracks Create a separate producer with `moq_publish_datagrams` and `moq_datagram_info`; replace `moq_publish_track_datagram` with `moq_publish_datagrams_append` on that handle, or `moq_publish_datagrams_insert` for an explicit sequence. `moq_consume_datagrams` now takes a subscriber priority before its callback and never subscribes to a stream track. Use `moq_publish_datagrams_demand` and `moq_datagram_demand_priority` for aggregate priority, and `moq_publish_datagrams_requests` / `moq_datagram_request_accept` for on-demand publishing. Finish or abort datagram producers separately. A zeroed datagram info is untimed, unlike the microsecond default of stream-track info. `moq_consume_datagrams` returns a negative code at once when the broadcast has neither the datagram track nor a datagram request handler, and a remote name without one ends its callback with a not-found error. diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index 898d7ea1002..16a4dfbc4b6 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -61,7 +61,6 @@ int32_t moq_session_request_free(uint32_t request); // Origin int32_t moq_origin_create(void); int32_t moq_origin_close(uint32_t origin); -int32_t moq_origin_create_broadcast(uint32_t origin, const char *path, uintptr_t path_len, uint32_t *broadcast); int32_t moq_origin_request(uint32_t origin, const char *path, uintptr_t path_len, const char *instance, uintptr_t instance_len, moq_status_callback on_broadcast, void *user_data); int32_t moq_origin_request_cancel(uint32_t task); int32_t moq_origin_follow(uint32_t origin, const char *path, uintptr_t path_len, const char *instance, uintptr_t instance_len, moq_follow_callback on_follow, void *user_data); @@ -72,11 +71,21 @@ int32_t moq_origin_announced_free(uint32_t announced); int32_t moq_origin_announced_cancel(uint32_t announced); // config (NULL for everything): filter is relative to the literal prefix, or NULL for **. hidden also lists `.`-named paths. Updates stay relative to the origin. -// Publishing: Announcement (a publication from moq_origin_create_broadcast or moq_broadcast_prepared_publish) -int32_t moq_publication_announce(uint32_t publication, const moq_announce_route *route); -// route (NULL for the default): a cost, and an optional stable instance with its epoch. Hops are the origin's to add. -int32_t moq_publication_unannounce(uint32_t publication); -int32_t moq_publication_free(uint32_t publication); +// Publishing: Routes (freeing one retracts it; moq_publish_close on its broadcast ends both) +int32_t moq_origin_route(uint32_t origin, const char *path, uintptr_t path_len, const moq_route_options *options); +int32_t moq_origin_route_prefix(uint32_t origin, const char *prefix, uintptr_t prefix_len, const moq_route_options *options, moq_status_callback on_request, void *user_data); +// options (NULL for the default): hidden until moq_route_announce, a cost, and an optional stable instance with its epoch. Hops are the origin's to add. +int32_t moq_route_broadcast(uint32_t route); +int32_t moq_route_instance(uint32_t route, moq_string *dst); +int32_t moq_route_announce(uint32_t route); +int32_t moq_route_withdraw(uint32_t route); +int32_t moq_route_set_cost(uint32_t route, uint64_t cost); +int32_t moq_route_free(uint32_t route); +int32_t moq_broadcast_request_path(uint32_t request, moq_string *dst); +int32_t moq_broadcast_request_serve(uint32_t request, uint32_t broadcast); +int32_t moq_broadcast_request_route(uint32_t request, const moq_route_options *options); +int32_t moq_broadcast_request_reject(uint32_t request, uint16_t error_code); +int32_t moq_broadcast_request_free(uint32_t request); // Publishing int32_t moq_publish_close(uint32_t broadcast); diff --git a/rs/moq-c/c-tests/audio-decode-output.c b/rs/moq-c/c-tests/audio-decode-output.c index 73e0364d40a..59e6092f93f 100644 --- a/rs/moq-c/c-tests/audio-decode-output.c +++ b/rs/moq-c/c-tests/audio-decode-output.c @@ -104,11 +104,11 @@ int main(void) { int32_t origin = moq_origin_create(); CHECK(origin > 0); const char *path = "audio-decode-output"; - uint32_t broadcast = 0; - int32_t publication = moq_origin_create_broadcast((uint32_t)origin, path, strlen(path), &broadcast); - CHECK(publication > 0); - CHECK(moq_publication_announce((uint32_t)publication, NULL) == 0); - CHECK(moq_publication_free((uint32_t)publication) == 0); + int32_t route = moq_origin_route((uint32_t)origin, path, strlen(path), NULL); + CHECK(route > 0); + int32_t created = moq_route_broadcast((uint32_t)route); + CHECK(created > 0); + uint32_t broadcast = (uint32_t)created; moq_audio_encoder_input input = {MOQ_AUDIO_SAMPLE_FORMAT_F32, 48000, 2}; moq_audio_encoder_output output = {"pcm", 3, 0, 0, 0, 0}; int32_t producer = moq_encode_audio((uint32_t)broadcast, "audio", 5, &input, &output, 0); @@ -155,6 +155,7 @@ int main(void) { CHECK(moq_consume_catalog_free((uint32_t)c.catalog) == 0); CHECK(moq_consume_catalog_cancel((uint32_t)catalogs) == 0); CHECK(moq_consume_close((uint32_t)c.broadcast) == 0); + CHECK(moq_route_free((uint32_t)route) == 0); CHECK(moq_publish_close((uint32_t)broadcast) == 0); CHECK(moq_origin_close((uint32_t)origin) == 0); pthread_mutex_lock(&c.mutex); diff --git a/rs/moq-c/c-tests/decode-output.c b/rs/moq-c/c-tests/decode-output.c index c8dbaf59741..f2c431a2a3e 100644 --- a/rs/moq-c/c-tests/decode-output.c +++ b/rs/moq-c/c-tests/decode-output.c @@ -243,13 +243,11 @@ int main(void) { if (origin <= 0) fail("error: moq_origin_create failed: %d\n", origin); const char *path = "c-decoder-output-test"; - uint32_t broadcast = 0; - int32_t publication = moq_origin_create_broadcast((uint32_t)origin, path, strlen(path), &broadcast); - if (publication <= 0) fail("error: moq_origin_create_broadcast failed: %d\n", publication); - if (moq_publication_announce((uint32_t)publication, NULL) < 0) - fail("error: moq_publication_announce failed (%s)\n", moq_error()); - if (moq_publication_free((uint32_t)publication) < 0) - fail("error: moq_publication_free failed (%s)\n", moq_error()); + int32_t route = moq_origin_route((uint32_t)origin, path, strlen(path), NULL); + if (route <= 0) fail("error: moq_origin_route failed: %d\n", route); + int32_t created = moq_route_broadcast((uint32_t)route); + if (created <= 0) fail("error: moq_route_broadcast failed: %d\n", created); + uint32_t broadcast = (uint32_t)created; moq_video_encoder_input input = {MOQ_VIDEO_PIXEL_FORMAT_RGBA, WIDTH, HEIGHT, {30000, 1001}}; moq_video_encoder_output output = {MOQ_VIDEO_CODEC_H264, 0, 0, MOQ_VIDEO_ENCODER_KIND_SOFTWARE, NULL, 0}; @@ -300,6 +298,8 @@ int main(void) { fail("error: moq_consume_close failed (%s)\n", moq_error()); if (moq_encode_video_finish((uint32_t)producer) < 0) fail("error: moq_encode_video_finish failed (%s)\n", moq_error()); + if (moq_route_free((uint32_t)route) < 0) + fail("error: moq_route_free failed (%s)\n", moq_error()); if (moq_publish_close((uint32_t)broadcast) < 0) fail("error: moq_publish_close failed (%s)\n", moq_error()); if (moq_origin_close((uint32_t)origin) < 0) diff --git a/rs/moq-c/c-tests/timestamps.c b/rs/moq-c/c-tests/timestamps.c index 8045f115f75..508262e62ea 100644 --- a/rs/moq-c/c-tests/timestamps.c +++ b/rs/moq-c/c-tests/timestamps.c @@ -78,11 +78,11 @@ int main(void) { int32_t origin = moq_origin_create(); CHECK(origin > 0); const char *path = "timestamps"; - uint32_t broadcast = 0; - int32_t publication = moq_origin_create_broadcast((uint32_t)origin, path, strlen(path), &broadcast); - CHECK(publication > 0); - CHECK(moq_publication_announce((uint32_t)publication, NULL) == 0); - CHECK(moq_publication_free((uint32_t)publication) == 0); + int32_t route = moq_origin_route((uint32_t)origin, path, strlen(path), NULL); + CHECK(route > 0); + int32_t created = moq_route_broadcast((uint32_t)route); + CHECK(created > 0); + uint32_t broadcast = (uint32_t)created; moq_track_info info = {0}; info.timescale = 90000; info.timescale_present = true; @@ -158,6 +158,7 @@ int main(void) { CHECK(moq_publish_json_stream_finish((uint32_t)json) == 0); CHECK(moq_publish_track_finish((uint32_t)track) == 0); CHECK(moq_publish_datagrams_finish((uint32_t)datagram_track) == 0); + CHECK(moq_route_free((uint32_t)route) == 0); CHECK(moq_publish_close((uint32_t)broadcast) == 0); CHECK(moq_origin_close((uint32_t)origin) == 0); WAIT_FOR(&c, c.request_done); diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 60abbd171ca..adb4ae1186a 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -918,42 +918,45 @@ pub struct moq_section { pub json_len: usize, } -/// How a publication advertises its exact path: a static cost and, optionally, a stable -/// instance. +/// How a route advertises itself: its visibility at creation, a static cost and, optionally, +/// a stable instance. /// -/// Pass one to [moq_publication_announce]. The hop chain is the origin's to build, -/// so a local publisher cannot claim relay hops it never took. Zeroed (cost 0, NULL -/// instance) is the default route. `instance` is borrowed for the duration of the call. +/// Pass one to [moq_origin_route], [moq_origin_route_prefix], or [moq_broadcast_request_route]. +/// The hop chain is the origin's to build, so a local publisher cannot claim relay hops it +/// never took. Zeroed (or NULL) is the default: visible at once, cost 0, under a fresh +/// instance. `instance` is borrowed for the duration of the call. #[repr(C)] #[derive(Clone, Copy)] -pub struct moq_announce_route { +pub struct moq_route_options { /// Preference among routes covering the same prefix: lower wins. A publisher /// sets its production cost here: zero for content it is already producing, /// larger for content it would have to start producing on demand. pub cost: u64, - /// A stable instance for the stream, NOT NULL terminated, or NULL (or empty) to keep the - /// one the publication minted. + /// A stable instance for the stream, NOT NULL terminated, or NULL (or empty) to mint a + /// fresh one when the route is created. /// - /// Every publication mints a fresh instance, kept across re-announcing, so a restarted - /// publisher is a new stream viewers restart onto. Set one only for a publisher that - /// continues its group sequences across restarts and raises `epoch` on each: readers - /// stitch every route of one instance together, so restarting the sequences under an - /// old instance splices unrelated groups into their tracks. Changing it hands followers - /// ([moq_origin_follow]) a new broadcast. + /// A route keeps its instance for its lifetime, across [moq_route_withdraw] and + /// [moq_route_announce], so a new route is a new stream viewers restart onto. Set one only + /// for a publisher that continues its group sequences across restarts and raises `epoch` + /// on each: readers stitch every route of one instance together, so restarting the + /// sequences under an old instance splices unrelated groups into their tracks. pub instance: *const c_char, /// The length in bytes of `instance`. pub instance_len: usize, /// Which run of a stable `instance` this is: only its highest epoch is eligible, cheaper /// or not. Ignored without one. pub epoch: u64, + /// Create the route hidden: it exists for nobody until [moq_route_announce]. For a + /// publisher that fills its catalog first. + pub hidden: bool, } -/// An observed route: hops, a static cost, and the stream's instance. +/// The read-only facts on a received route: hops, a static cost, and the stream's instance. /// /// Carried by [moq_announce_event]. Its pointers borrow the announcement's storage. #[repr(C)] #[derive(Clone, Copy)] -pub struct moq_route { +pub struct moq_route_info { /// Hop ids of the relay hops the route traversed, oldest first. 0 is the /// anonymous mark, which ranks the route below every fully identified one. /// A route announced on this origin has none. @@ -966,18 +969,46 @@ pub struct moq_route { pub instance: moq_string, } -/// Parse a [moq_announce_route], treating NULL as the default. +/// Parse [moq_route_options], treating NULL as the default. +/// +/// The instance parses as at every API that takes one: NULL or empty names none. /// /// # Safety -/// `route` may be NULL, or must point at a readable [moq_announce_route] whose `instance` +/// `options` may be NULL, or must point at a readable [moq_route_options] whose `instance` /// pointer is valid for `instance_len` bytes. -unsafe fn parse_announce_route(route: *const moq_announce_route) -> Result { - let Some(route) = (unsafe { route.as_ref() }) else { - return Ok(moq_net::origin::Route::default()); +unsafe fn parse_route_options(options: *const moq_route_options) -> Result { + let hidden = unsafe { options.as_ref() }.is_some_and(|options| options.hidden); + unsafe { route_options(options, hidden) } +} + +/// [parse_route_options] for an exact route: created hidden so [State::exact_route] attaches +/// the catalog track before anyone can find it, with whether the caller asked it visible. +/// +/// # Safety +/// As [parse_route_options]. +unsafe fn parse_exact_route_options( + options: *const moq_route_options, +) -> Result<(moq_net::origin::RouteOptions, bool), Error> { + let visible = unsafe { options.as_ref() }.is_none_or(|options| !options.hidden); + Ok((unsafe { route_options(options, true)? }, visible)) +} + +/// # Safety +/// As [parse_route_options]. +unsafe fn route_options( + options: *const moq_route_options, + hidden: bool, +) -> Result { + let mut out = match hidden { + true => moq_net::origin::RouteOptions::hidden(), + false => moq_net::origin::RouteOptions::default(), + }; + let Some(options) = (unsafe { options.as_ref() }) else { + return Ok(out); }; - let mut out = moq_net::origin::Route::default().with_cost(moq_net::origin::Cost::new(route.cost)); - if let Some(instance) = unsafe { parse_instance(route.instance, route.instance_len)? } { - out = out.with_instance(instance, route.epoch); + out = out.with_cost(options.cost); + if let Some(instance) = unsafe { parse_instance(options.instance, options.instance_len)? } { + out = out.with_instance(instance, options.epoch); } Ok(out) } @@ -1035,7 +1066,7 @@ pub struct moq_announce_event { /// The route serving the prefix. On `MOQ_ANNOUNCE_KIND_ABSENT` it carries the last /// advertised route. - pub route: moq_route, + pub route: moq_route_info, } /// Where a session is in its lifecycle, reported by [moq_connection_state]. @@ -1994,89 +2025,178 @@ pub extern "C" fn moq_origin_create() -> i32 { ffi::enter(move || State::lock().origin.create()) } -/// Create a broadcast at `path` on an origin, for publishing media tracks. +/// Create a route at exactly `path` on an origin, owning a new broadcast to fill. /// -/// Writes the broadcast handle to fill with the `moq_publish_*` functions to -/// `broadcast`, and returns a positive publication handle that announces it, or a -/// negative code on failure. The broadcast is invisible and unroutable, on this -/// origin and its peers alike, until [moq_publication_announce]. Fill it, then -/// announce it. [moq_publish_close] ends it for good; -/// [moq_publication_free] releases the publication handle without retracting. +/// Returns a positive route handle, or a negative code on failure. [moq_route_broadcast] +/// gives the broadcast handle to fill with the `moq_publish_*` functions. The route is +/// visible at once unless `options` sets `hidden`: a hidden route is invisible and +/// unroutable, on this origin and its peers alike, until [moq_route_announce], so create +/// it hidden to fill the catalog first. NULL `options` is the default. +/// +/// Hold the route while the broadcast should stay announced: [moq_route_free] retracts it, +/// and [moq_publish_close] ends both. /// /// # Safety /// - The caller must ensure that path is a valid pointer to path_len bytes of data. -/// - `broadcast` must point at writable storage for one handle. +/// - `options` may be NULL, or must point at a readable [moq_route_options]. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_origin_create_broadcast( +pub unsafe extern "C" fn moq_origin_route( origin: u32, path: *const c_char, path_len: usize, - broadcast: *mut u32, + options: *const moq_route_options, ) -> i32 { ffi::enter(move || { let origin = ffi::parse_id(origin)?; let path = unsafe { ffi::parse_str(path, path_len)? }; - let broadcast_out = unsafe { broadcast.as_mut() }.ok_or(Error::InvalidPointer)?; - + let (options, visible) = unsafe { parse_exact_route_options(options)? }; let mut state = State::lock(); - let publication = state.origin.create_broadcast(origin, path)?; - let (publication, broadcast) = state.publish.create_publication(publication)?; - *broadcast_out = broadcast.into(); - Ok(publication) + let route = state.origin.route(origin, path, options)?; + state.exact_route(route, visible) }) } -/// Advertise `prefix` and serve the requests beneath it. +/// Create a route over `prefix` that serves the requests beneath it. /// /// A route claims `prefix` and every path beneath it (the empty prefix claims /// every path). A service that only serves some of them advertises the -/// covering prefix and rejects the rest as they are requested. `on_request` is -/// required: a NULL callback is refused before the route is advertised. It is -/// invoked with a positive request handle for each -/// pending broadcast, then exactly once more with a terminal code: `0` (stopped -/// cleanly, including after [moq_origin_requests_cancel]) or a negative error. +/// covering prefix and rejects the rest as they are requested. NULL `options` is the +/// default. +/// +/// `on_request` is required: a NULL callback is refused before the route is advertised. +/// It is invoked with a positive request handle for each pending broadcast (answer it with +/// [moq_broadcast_request_serve], [moq_broadcast_request_route], or +/// [moq_broadcast_request_reject]), then exactly once more with a terminal code: `0` +/// (stopped cleanly, after [moq_route_free] or the origin closing) or a negative error. /// After the terminal (`<= 0`) callback, `user_data` is never touched again. /// -/// Returns a non-zero handle on success, or a negative code on failure. +/// Returns a positive route handle on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure that prefix is a valid pointer to prefix_len bytes of data. +/// - `options` may be NULL, or must point at a readable [moq_route_options]. /// - `on_request` must be non-NULL; a missing callback is refused before the route is advertised. /// - The caller must keep `user_data` valid until the terminal (`<= 0`) `on_request` callback. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_origin_requests( +pub unsafe extern "C" fn moq_origin_route_prefix( origin: u32, prefix: *const c_char, prefix_len: usize, + options: *const moq_route_options, on_request: ffi::moq_status_callback, user_data: *mut c_void, ) -> i32 { ffi::enter(move || { let origin = ffi::parse_id(origin)?; let prefix = unsafe { ffi::parse_str(prefix, prefix_len)? }; + let options = unsafe { parse_route_options(options)? }; let on_request = unsafe { ffi::OnStatus::new(user_data, on_request)? }; - State::lock().origin.dynamic(origin, prefix, on_request) + State::lock().origin.route_prefix(origin, prefix, options, on_request) }) } -/// Stop serving and retract the route. +/// The broadcast an exact route owns, to fill with the `moq_publish_*` functions. /// -/// Returns immediately: zero on success, or a negative code if already closed. -/// The [moq_origin_requests] `on_request` callback still fires once more with a -/// terminal `0` (or a negative error), and that final callback is where -/// `user_data` should be released. +/// Returns the same positive broadcast handle on every call, or a negative code: a prefix +/// route owns none (`MOQ_ERROR_BROADCAST_NOT_FOUND`), and neither does a route whose +/// broadcast [moq_publish_close] ended. #[unsafe(no_mangle)] -pub extern "C" fn moq_origin_requests_cancel(dynamic: u32) -> i32 { +pub extern "C" fn moq_route_broadcast(route: u32) -> i32 { ffi::enter(move || { - let dynamic = ffi::parse_id(dynamic)?; - State::lock().origin.dynamic_close(dynamic) + let route = ffi::parse_id(route)?; + let state = State::lock(); + let broadcast = state.origin.route_broadcast(route)?; + match state.publish.contains(broadcast) { + true => Ok(broadcast), + false => Err(Error::BroadcastNotFound), + } + }) +} + +/// The stream a route serves, minted at creation unless its options named one. +/// +/// Kept across [moq_route_withdraw] and [moq_route_announce]. The destination borrows the +/// route's storage until [moq_route_free]. +/// +/// Returns zero on success, or a negative code on failure. +/// +/// # Safety +/// - `dst` must point at a writable [moq_string]. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_route_instance(route: u32, dst: *mut moq_string) -> i32 { + ffi::enter(move || { + let route = ffi::parse_id(route)?; + let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; + State::lock().origin.route_instance(route, dst) }) } -/// The path of a broadcast request delivered to a [moq_origin_requests] callback. +/// Make a route visible, or keep it so. +/// +/// A route from [moq_broadcast_request_route] also answers the requesters waiting on its +/// path. Fails once its broadcast closed, and when a request's route can never announce +/// because the request was released or its prefix route retracted meanwhile. +/// +/// Returns zero on success, or a negative code on failure. +#[unsafe(no_mangle)] +pub extern "C" fn moq_route_announce(route: u32) -> i32 { + ffi::enter(move || { + let route = ffi::parse_id(route)?; + State::lock().origin.route_with(route, |route| route.announce()) + }) +} + +/// Hide a route from everyone, keeping its broadcast and instance. +/// +/// Local consumers and peers alike stop discovering and requesting it; tracks already in +/// flight carry on, and [moq_route_announce] brings the same stream back. +/// Returns zero on success, or a negative code on failure. +#[unsafe(no_mangle)] +pub extern "C" fn moq_route_withdraw(route: u32) -> i32 { + ffi::enter(move || { + let route = ffi::parse_id(route)?; + State::lock().origin.route_with(route, |route| { + route.withdraw(); + Ok(()) + }) + }) +} + +/// Re-price a route in place: lower wins among routes covering the same prefix. +/// +/// A hidden route keeps the price for when it next announces. Fails once its broadcast +/// closed. Returns zero on success, or a negative code on failure. +#[unsafe(no_mangle)] +pub extern "C" fn moq_route_set_cost(route: u32, cost: u64) -> i32 { + ffi::enter(move || { + let route = ffi::parse_id(route)?; + State::lock().origin.route_with(route, |route| route.set_cost(cost)) + }) +} + +/// Release a route handle, retracting the route. +/// +/// An exact route's broadcast handle stays the caller's until [moq_publish_close]. A prefix +/// route stops serving: requests not yet delivered are rejected, and its `on_request` +/// callback fires once more with a terminal `0`, which is where `user_data` should be +/// released. +/// +/// Returns zero on success, or a negative code if the handle is unknown. +#[unsafe(no_mangle)] +pub extern "C" fn moq_route_free(route: u32) -> i32 { + ffi::enter(move || { + let route = ffi::parse_id(route)?; + // Dropped outside the lock: retracting refuses a job's waiting requesters. + let route = State::lock().origin.route_take(route)?; + drop(route); + Ok(()) + }) +} + +/// The path of a broadcast request delivered to a [moq_origin_route_prefix] callback. /// /// The destination borrows the request's storage: copy it out before -/// [moq_broadcast_request_serve], [moq_broadcast_request_prepare], +/// [moq_broadcast_request_serve], [moq_broadcast_request_route], /// [moq_broadcast_request_reject], or [moq_broadcast_request_free]. /// /// Returns a zero on success, or a negative code on failure. @@ -2095,7 +2215,7 @@ pub unsafe extern "C" fn moq_broadcast_request_path(request: u32, dst: *mut moq_ /// Serve a held consumer under the prefix route's instance without announcing an exact route. /// /// Every answer at this path must continue the same sequences and bytes. Start a new -/// prefix route for different content, or prepare and publish a job with its own instance. +/// prefix route for different content, or route a job with its own instance. /// Consumes the request handle; the consumer remains owned by the caller. /// Returns zero on success, or a negative error. #[unsafe(no_mangle)] @@ -2113,55 +2233,28 @@ pub extern "C" fn moq_broadcast_request_serve(request: u32, broadcast: u32) -> i }) } -/// Start a broadcast request answer as a new stream under a fresh instance, hidden until -/// published. +/// Answer a broadcast request with the path's own exact route, owning a new broadcast. /// -/// Consumes the request handle, writes the new broadcast handle to `broadcast` -/// (which cannot announce itself; only [moq_broadcast_prepared_publish] does), -/// and returns a positive prepared-answer handle or a negative error. +/// Consumes the request handle and returns a positive route handle, or a negative error. +/// The route serves a fresh instance unless `options` names one, so a job that restarts is +/// a new stream. Created visible, it announces now and answers the waiting requesters; +/// created hidden, they wait until [moq_route_announce], so the job can fill its catalog +/// first, and freeing the route before then refuses them. Ending the route withdraws only +/// this path. Unreadable `options` fail without consuming the request. /// /// # Safety -/// - `broadcast` must point at writable storage for one handle. +/// - `options` may be NULL, or must point at a readable [moq_route_options]. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_broadcast_request_prepare(request: u32, broadcast: *mut u32) -> i32 { +pub unsafe extern "C" fn moq_broadcast_request_route(request: u32, options: *const moq_route_options) -> i32 { ffi::enter(move || { let request = ffi::parse_id(request)?; - let broadcast_out = unsafe { broadcast.as_mut() }.ok_or(Error::InvalidPointer)?; + let (options, visible) = unsafe { parse_exact_route_options(options)? }; let mut state = State::lock(); let (pending, driver) = state.origin.broadcast_request_take(request)?; - let prepared = pending.prepare()?; - let broadcast = state.publish.create((prepared.broadcast().clone(), driver.clone()))?; - let id = state.origin.prepared_insert(prepared, driver, broadcast)?; - *broadcast_out = broadcast.into(); - Ok(id) - }) -} - -/// Publish a prepared claim answer and resolve every waiting requester. -/// -/// Consumes the prepared handle and returns a positive publication handle, or a -/// negative code on failure. The broadcast handle returned by -/// [moq_broadcast_request_prepare] remains owned by the caller. -#[unsafe(no_mangle)] -pub extern "C" fn moq_broadcast_prepared_publish(prepared: u32) -> i32 { - ffi::enter(move || { - let prepared = ffi::parse_id(prepared)?; - let mut state = State::lock(); - let (prepared, driver, broadcast) = state.origin.prepared_take(prepared)?; driver.check()?; - let result = state.publish.admit(broadcast, prepared, driver.clone()); + let result = pending.route(options); driver.check()?; - result - }) -} - -/// Free a prepared claim answer without publishing it. -#[unsafe(no_mangle)] -pub extern "C" fn moq_broadcast_prepared_free(prepared: u32) -> i32 { - ffi::enter(move || { - let prepared = ffi::parse_id(prepared)?; - State::lock().origin.prepared_take(prepared)?; - Ok(()) + state.exact_route((result?, driver), visible) }) } @@ -2181,7 +2274,7 @@ pub extern "C" fn moq_broadcast_request_reject(request: u32, error_code: u16) -> }) } -/// Free a broadcast request without accepting or rejecting it. +/// Free a broadcast request without answering it. /// /// Dropping the request rejects it. Returns a zero on success, or a negative /// code if the handle is unknown. @@ -2374,8 +2467,8 @@ pub extern "C" fn moq_origin_follow_cancel(task: u32) -> i32 { /// /// Owns discovery of the path and retries route churn while resolving one publisher instance. /// It fails as unroutable once discovery has synced without a covering route, including a -/// broadcast created but not announced. No separate announcement stream is needed. -/// Serve on-demand paths with [moq_origin_requests]. +/// hidden route not announced yet. No separate announcement stream is needed. +/// Serve on-demand paths with [moq_origin_route_prefix]. /// /// `instance` is the only stream to accept, or NULL (or empty) for any. A request pinned to an /// instance that does not serve the path is unroutable. @@ -2441,8 +2534,7 @@ unsafe fn parse_instance(instance: *const c_char, instance_len: usize) -> Result /// Close an origin and clean up its resources. /// -/// The origin keeps running while a broadcast published on it or a -/// [moq_origin_requests] handler lives; close or cancel those to end it. +/// The origin keeps running while a route created on it lives; free those to end it. /// /// Returns a zero on success, or a negative code on failure. #[unsafe(no_mangle)] @@ -2453,51 +2545,6 @@ pub extern "C" fn moq_origin_close(origin: u32) -> i32 { }) } -/// Advertise a publication's exact path as a route. -/// -/// Announcing again re-prices the route in place, or restarts it under another instance. A -/// NULL `route` uses the default: cost 0, under the instance the publication minted. Until -/// announced, the broadcast is invisible and unroutable for local consumers and peers alike. -/// Fails once the broadcast closed. -/// -/// Returns a zero on success, or a negative code on failure. -/// -/// # Safety -/// - `route` may be NULL, or must point at a readable [moq_announce_route]. -#[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_publication_announce(publication: u32, route: *const moq_announce_route) -> i32 { - ffi::enter(move || { - let publication = ffi::parse_id(publication)?; - let route = unsafe { parse_announce_route(route)? }; - State::lock().publish.announce(publication, route) - }) -} - -/// Retract a publication's exact-path advertisement, if any. -/// -/// Local consumers and peers alike stop discovering and requesting it; tracks already in -/// flight carry on, and announcing again brings it back. Fails once the broadcast closed. -/// Returns a zero on success, or a negative code on failure. -#[unsafe(no_mangle)] -pub extern "C" fn moq_publication_unannounce(publication: u32) -> i32 { - ffi::enter(move || { - let publication = ffi::parse_id(publication)?; - State::lock().publish.unannounce(publication) - }) -} - -/// Release a publication handle. -/// -/// The broadcast and its route stay as they are; [moq_publish_close] ends them. -/// Returns a zero on success, or a negative code on failure. -#[unsafe(no_mangle)] -pub extern "C" fn moq_publication_free(publication: u32) -> i32 { - ffi::enter(move || { - let publication = ffi::parse_id(publication)?; - State::lock().publish.publication_free(publication) - }) -} - /// End a broadcast for good and release its handle. /// /// The origin retracts the path immediately and serves no new tracks. Every media, raw track, @@ -2911,7 +2958,7 @@ pub unsafe extern "C" fn moq_publish_video_properties(broadcast: u32, properties /// /// This is the producer counterpart to [moq_consume_video_config]: instead of /// reading a rendition out of a catalog, it writes one into the catalog of a -/// broadcast created with [moq_origin_create_broadcast]. The rendition is keyed by +/// broadcast from [moq_route_broadcast]. The rendition is keyed by /// `config.name`; calling this again with the same name replaces the rendition /// you declared, so a config can be refined in place. It fails when a /// [moq_publish_video] track owns the name, since that track publishes and @@ -3048,7 +3095,7 @@ pub unsafe extern "C" fn moq_publish_audio_remove(broadcast: u32, name: *const c /// /// This is the producer counterpart to [moq_consume_catalog_section] / /// [moq_consume_catalog_section_at]: it writes an arbitrary top-level JSON key into the -/// catalog of a broadcast created with [moq_origin_create_broadcast], beyond the +/// catalog of a broadcast from [moq_route_broadcast], beyond the /// `video`/`audio` keys owned by the media pipeline. Calling it again with the /// same name replaces the section. The updated catalog is published to /// subscribers automatically. diff --git a/rs/moq-c/src/origin.rs b/rs/moq-c/src/origin.rs index b1eb57a1e4e..ead137e4192 100644 --- a/rs/moq-c/src/origin.rs +++ b/rs/moq-c/src/origin.rs @@ -3,7 +3,7 @@ use tokio::sync::oneshot; use crate::ffi::{OnFollow, OnStatus}; use crate::task::Task; -use crate::{Error, Id, NonZeroSlab, State, moq_announce_event, moq_announce_kind, moq_route, moq_string}; +use crate::{Error, Id, NonZeroSlab, State, moq_announce_event, moq_announce_kind, moq_route_info, moq_string}; /// Global state managing all active resources. /// @@ -25,17 +25,18 @@ pub struct Origin { /// Pending requests. Close signals shutdown; the task delivers a final callback, then removes itself. consume_task: NonZeroSlab, + /// Routes created on an origin, retracted when freed. + routes: NonZeroSlab, + /// Follows. Close signals shutdown; the task delivers its end event, then removes itself. follow_task: NonZeroSlab>, - /// Served routes from [Self::dynamic], retracted when the handle is closed. - dynamic: NonZeroSlab, + /// Request deliveries of prefix routes. Freeing the route signals shutdown; the task + /// delivers a final callback, then removes itself. + route_requests: NonZeroSlab, - /// Broadcast requests delivered to a dynamic handler, freed after accept/reject. + /// Broadcast requests delivered to a prefix route's callback, freed after serve/route/reject. broadcast_request: NonZeroSlab<(moq_net::origin::Request, crate::ffi::Background)>, - - /// Claim answers being filled before their exact route is announced. - prepared: NonZeroSlab<(moq_net::origin::Prepared, crate::ffi::Background, Id)>, } #[derive(Clone)] @@ -116,20 +117,48 @@ impl AnnouncedRecord { _captures: captures, capture_views, kind, - hops: update.route.hops.iter().map(|hop| hop.id()).collect(), - cost: update.route.cost.value(), - instance: update - .route - .instance - .map(|instance| instance.to_string()) - .unwrap_or_default(), + hops: update.route.hops().iter().map(|hop| hop.id()).collect(), + cost: update.route.cost().value(), + instance: update.route.instance().to_string(), } } } -struct DynamicEntry { - task: Task, - inner: Option, +impl State { + /// Store an exact route and the fill handle of the broadcast it owns, returning the route. + /// + /// The route is created hidden, so its catalog track is attached before `visible` announces + /// it and a reader that finds it finds the catalog. + pub fn exact_route( + &mut self, + (route, driver): (moq_net::origin::Route, crate::ffi::Background), + visible: bool, + ) -> Result { + let broadcast = self.publish.create((route.broadcast().clone(), driver.clone()))?; + let announced = match visible { + true => route.announce().map_err(Error::from), + false => Ok(()), + }; + announced + .and_then(|()| self.origin.route_insert(route, driver, broadcast)) + .inspect_err(|_| { + self.publish.discard(broadcast); + }) + } +} + +struct RouteEntry { + inner: moq_net::origin::Route, + driver: crate::ffi::Background, + /// Minted at creation and kept for the route's lifetime, borrowed by [Origin::route_instance]. + instance: String, + /// An exact route's broadcast fill handle, or a prefix route's request delivery task. + kind: RouteKind, +} + +enum RouteKind { + Exact { broadcast: Id }, + Prefix { requests: Id }, } impl Origin { @@ -202,7 +231,7 @@ impl Origin { captures: announced.capture_views.as_ptr(), captures_len: announced.capture_views.len(), kind: announced.kind, - route: moq_route { + route: moq_route_info { hops: announced.hops.as_ptr(), hops_len: announced.hops.len(), cost: announced.cost, @@ -358,49 +387,83 @@ impl Origin { self.consume_task.close(task, Error::NotFound) } - /// Create an unannounced broadcast at `path` on an origin. + /// Create an exact route at `path`, returning the route and the broadcast it owns. /// /// Errors with [`Error::Moq`] if the path is outside the origin's scope. - pub fn create_broadcast>>( + pub fn route( &self, origin: Id, - path: P, - ) -> Result<(moq_net::origin::Publication, crate::ffi::Background), Error> { + path: &str, + options: moq_net::origin::RouteOptions, + ) -> Result<(moq_net::origin::Route, crate::ffi::Background), Error> { let origin = self.get(origin)?; - let result = origin.producer.create_broadcast(path); + let result = origin.producer.route(path, options); origin.driver.check()?; Ok((result?, origin.driver.clone())) } - /// Advertise `prefix` and serve requests beneath it, delivering each as a - /// broadcast-request handle via `on_request`. - pub fn dynamic(&mut self, origin: Id, prefix: &str, on_request: OnStatus) -> Result { - let origin = self.active.get(origin).ok_or(Error::OriginNotFound)?; - origin.driver.check()?; + /// Store an exact route whose broadcast fill handle is `broadcast`. + pub fn route_insert( + &mut self, + route: moq_net::origin::Route, + driver: crate::ffi::Background, + broadcast: Id, + ) -> Result { + self.routes.insert(RouteEntry { + instance: route.instance().to_string(), + inner: route, + driver, + kind: RouteKind::Exact { broadcast }, + }) + } + + /// Create a prefix route, delivering each request beneath it as a broadcast-request handle + /// via `on_request`. + pub fn route_prefix( + &mut self, + origin: Id, + prefix: &str, + options: moq_net::origin::RouteOptions, + on_request: OnStatus, + ) -> Result { + let origin = self.get(origin)?; let driver = origin.driver.clone(); - let result = origin.producer.requests(prefix); - origin.driver.check()?; - let inner = result?; + let result = origin.producer.route_prefix(prefix, options); + driver.check()?; + let route = result?; + let instance = route.instance().to_string(); + + // The route first, so the delivery task finds it once it runs; it cannot lock the + // state before this call returns. let (task, close) = Task::new(on_request); - let id = self.dynamic.insert(DynamicEntry { - task, - inner: Some(inner), - })?; + let requests = self.route_requests.insert(task)?; + let id = match self.routes.insert(RouteEntry { + inner: route, + driver: driver.clone(), + instance, + kind: RouteKind::Prefix { requests }, + }) { + Ok(id) => id, + Err(err) => { + self.route_requests.remove(requests); + return Err(err); + } + }; - let request_driver = driver.clone(); tokio::spawn(async move { - let res = crate::ffi::run(driver.watch(Self::run_dynamic(id, close, request_driver))).await; - let entry = State::lock().origin.dynamic.remove(id); + let res = crate::ffi::run(driver.watch(Self::run_requests(id, on_request, close, driver.clone()))).await; + let entry = State::lock().origin.route_requests.remove(requests); if let Some(entry) = entry { - entry.task.callback.call(res); + entry.callback.call(res); } }); Ok(id) } - async fn run_dynamic( - id: Id, + async fn run_requests( + route: Id, + callback: OnStatus, mut close: oneshot::Receiver<()>, driver: crate::ffi::Background, ) -> Result<(), Error> { @@ -408,39 +471,74 @@ impl Origin { let request = tokio::select! { biased; _ = &mut close => return Ok(()), - res = kio::wait(|waiter| { + request = kio::wait(|waiter| { let state = State::lock(); - match state.origin.dynamic.get(id).and_then(|entry| entry.inner.as_ref()) { - Some(dynamic) => dynamic.poll_requested_broadcast(waiter), - None => std::task::Poll::Ready(Err(moq_net::Error::Closed)), + match state.origin.routes.get(route) { + Some(entry) => entry.inner.poll_requested(waiter), + None => std::task::Poll::Ready(None), } - }) => match res { - Ok(request) => request, - Err(moq_net::Error::Closed) => return Ok(()), - Err(err) => return Err(err.into()), + }) => match request { + Some(request) => request, + // Retracted, or the origin closed. + None => return Ok(()), }, }; + // Hold the lock only to buffer the request; release it before the callback. let request_id = State::lock() .origin .broadcast_request .insert((request, driver.clone()))?; - let callback = State::lock().origin.dynamic.get(id).map(|entry| entry.task.callback); - let Some(callback) = callback else { - return Ok(()); - }; callback.call(request_id); } } - pub fn dynamic_close(&mut self, dynamic: Id) -> Result<(), Error> { - let entry = self.dynamic.get_mut(dynamic).ok_or(Error::NotFound)?; - let inner = entry.inner.take().ok_or(Error::NotFound)?; - entry.task.close(Error::NotFound)?; - drop(inner); + fn route_entry(&self, route: Id) -> Result<&RouteEntry, Error> { + let entry = self.routes.get(route).ok_or(Error::NotFound)?; + entry.driver.check()?; + Ok(entry) + } + + /// Run `f` against the route, then check its origin is still healthy. + pub fn route_with( + &self, + route: Id, + f: impl FnOnce(&moq_net::origin::Route) -> Result, + ) -> Result { + let entry = self.route_entry(route)?; + let result = f(&entry.inner); + entry.driver.check()?; + Ok(result?) + } + + /// An exact route's broadcast fill handle, or [`Error::BroadcastNotFound`] on a prefix route. + pub fn route_broadcast(&self, route: Id) -> Result { + match self.route_entry(route)?.kind { + RouteKind::Exact { broadcast } => Ok(broadcast), + RouteKind::Prefix { .. } => Err(Error::BroadcastNotFound), + } + } + + pub fn route_instance(&self, route: Id, dst: &mut moq_string) -> Result<(), Error> { + let entry = self.route_entry(route)?; + *dst = moq_string { + data: entry.instance.as_ptr().cast::(), + len: entry.instance.len(), + }; Ok(()) } + /// Release a route handle and stop a prefix route's request delivery, returning the route + /// for the caller to retract by dropping it. + pub fn route_take(&mut self, route: Id) -> Result { + let entry = self.routes.remove(route).ok_or(Error::NotFound)?; + if let RouteKind::Prefix { requests } = entry.kind { + // Already gone once the origin closed and the task delivered its terminal callback. + let _ = self.route_requests.close(requests, Error::NotFound); + } + Ok(entry.inner) + } + pub fn broadcast_request_path(&self, request: Id, dst: &mut crate::moq_string) -> Result<(), Error> { let request = self.broadcast_request.get(request).ok_or(Error::NotFound)?; let path = request.0.path(); @@ -458,22 +556,6 @@ impl Origin { self.broadcast_request.remove(request).ok_or(Error::NotFound) } - pub fn prepared_insert( - &mut self, - prepared: moq_net::origin::Prepared, - driver: crate::ffi::Background, - broadcast: Id, - ) -> Result { - self.prepared.insert((prepared, driver, broadcast)) - } - - pub fn prepared_take( - &mut self, - prepared: Id, - ) -> Result<(moq_net::origin::Prepared, crate::ffi::Background, Id), Error> { - self.prepared.remove(prepared).ok_or(Error::NotFound) - } - pub fn close(&mut self, origin: Id) -> Result<(), Error> { self.active.remove(origin).ok_or(Error::OriginNotFound)?; Ok(()) @@ -483,36 +565,35 @@ impl Origin { #[cfg(test)] mod supervision_tests { use super::*; + use moq_net::origin::RouteOptions; #[tokio::test] - async fn a_broadcast_keeps_the_origin_failure_after_its_origin_handle_is_released() { + async fn a_route_keeps_the_origin_failure_after_its_origin_handle_is_released() { let (producer, completion, trigger) = crate::ffi::panicking_origin(); - let mut origins = Origin::default(); - let origin = origins + let mut state = State::new(); + let origin = state + .origin .active .insert(Producer { producer, driver: completion.clone(), }) .unwrap(); - let mut publish = crate::publish::Publish::default(); - let (publication, _broadcast) = publish - .create_publication(origins.create_broadcast(origin, "retained").unwrap()) - .unwrap(); - origins.close(origin).unwrap(); + let retained = state.origin.route(origin, "retained", RouteOptions::hidden()).unwrap(); + let route = state.exact_route(retained, false).unwrap(); + state.origin.close(origin).unwrap(); *trigger .write() .unwrap_or_else(|_| unreachable!("test keeps its panic trigger open")) = true; assert!(matches!(completion.finished().await, Err(Error::Panic))); drop(completion); assert!(matches!( - publish.announce(publication, Default::default()), + state.origin.route_with(route, |route| route.announce()), Err(Error::Panic) )); - let healthy = origins.create().unwrap(); - let (publication, _broadcast) = publish - .create_publication(origins.create_broadcast(healthy, "healthy").unwrap()) - .unwrap(); - publish.announce(publication, Default::default()).unwrap(); + let healthy = state.origin.create().unwrap(); + let healthy = state.origin.route(healthy, "healthy", RouteOptions::hidden()).unwrap(); + let route = state.exact_route(healthy, false).unwrap(); + state.origin.route_with(route, |route| route.announce()).unwrap(); } } diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 9fc5eddc906..b399493045b 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -342,17 +342,6 @@ pub struct Publish { /// Group requests delivered to a handler, freed on accept, abort, or free. group_request: NonZeroSlab, - - /// Announcement handles for origin broadcasts, freed by the caller. - publications: NonZeroSlab, -} - -/// A broadcast's announcement capability, beside the fill handle it was published with. -struct Publication { - driver: crate::ffi::Background, - /// The fill handle, which leaves the registry once the broadcast closes. - broadcast: Id, - inner: moq_net::origin::Publication, } impl Publish { @@ -390,77 +379,14 @@ impl Publish { Ok(id) } - /// Store an origin broadcast's fill handle and its publication, returning both handles. - pub fn create_publication( - &mut self, - (publication, driver): (moq_net::origin::Publication, crate::ffi::Background), - ) -> Result<(Id, Id), Error> { - let broadcast = self.create((publication.broadcast().clone(), driver.clone()))?; - let id = self.publications.insert(Publication { - broadcast, - driver, - inner: publication, - }); - match id { - Ok(id) => Ok((id, broadcast)), - Err(err) => { - self.broadcasts.remove(broadcast); - Err(err) - } - } - } - - /// Publish a prepared answer filled through `id`, returning its publication handle. - pub fn admit( - &mut self, - id: Id, - prepared: moq_net::origin::Prepared, - driver: crate::ffi::Background, - ) -> Result { - if let Some(broadcast) = self.broadcasts.get(id) { - broadcast.driver.check()?; - if !broadcast.producer.is_clone(prepared.broadcast()) { - return Err(Error::BroadcastNotFound); - } - } - // A closed fill left this registry, and native admission refuses it. - let publication = prepared.publish()?; - self.publications.insert(Publication { - driver, - broadcast: id, - inner: publication, - }) + /// Whether `id` names a broadcast fill handle that has not been closed. + pub fn contains(&self, id: Id) -> bool { + self.broadcasts.get(id).is_some() } - /// The publication, refused with `Closed` once its broadcast closed. - fn publication(&self, id: Id) -> Result<&Publication, Error> { - let publication = self.publications.get(id).ok_or(Error::NotFound)?; - publication.driver.check()?; - if self.broadcasts.get(publication.broadcast).is_none() { - return Err(Error::Moq(moq_net::Error::Closed)); - } - Ok(publication) - } - - /// Advertise the broadcast's exact path as a route. Announcing again re-prices - /// in place. Until announced, the broadcast is invisible and unroutable. - pub fn announce(&mut self, publication: Id, route: moq_net::origin::Route) -> Result<(), Error> { - let publication = self.publication(publication)?; - let result = publication.inner.announce(route); - publication.driver.check()?; - Ok(result?) - } - - /// Retract the broadcast's exact-path advertisement, if any. - pub fn unannounce(&mut self, publication: Id) -> Result<(), Error> { - self.publication(publication)?.inner.unannounce(); - Ok(()) - } - - /// Release a publication handle; the broadcast and its route stay as they are. - pub fn publication_free(&mut self, publication: Id) -> Result<(), Error> { - self.publications.remove(publication).ok_or(Error::NotFound)?; - Ok(()) + /// Drop a fill handle that never reached the caller. + pub fn discard(&mut self, id: Id) { + self.broadcasts.remove(id); } /// The broadcast's track producer. @@ -1695,53 +1621,14 @@ mod children_tests { mod supervision_tests { use super::*; - #[tokio::test(start_paused = true)] - async fn admission_must_match_the_broadcast_it_filled() { - let origin = moq_tokio::origin::spawn(); - let claim = origin.requests("room").unwrap(); - let pending = origin.consume().request("room/first", None); - let prepared = claim.requested_broadcast().await.unwrap().prepare().unwrap(); - let mut publish = Publish::default(); - let first = publish - .create((prepared.broadcast().clone(), Default::default())) - .unwrap(); - let alias = { - let original = publish.broadcast(first).unwrap(); - Broadcast { - driver: original.driver.clone(), - producer: original.producer.clone(), - catalog: original.catalog.clone(), - video: Default::default(), - audio: Default::default(), - children: Default::default(), - ended: false, - } - }; - let clone = publish.broadcasts.insert(alias).unwrap(); - assert_ne!(first, clone); - let publication = publish.admit(clone, prepared, Default::default()).unwrap(); - pending.await.unwrap(); - publish.unannounce(publication).unwrap(); - - let pending = origin.consume().request("room/second", None); - let prepared = claim.requested_broadcast().await.unwrap().prepare().unwrap(); - publish - .create((prepared.broadcast().clone(), Default::default())) - .unwrap(); - assert!(matches!( - publish.admit(first, prepared, Default::default()), - Err(Error::BroadcastNotFound) - )); - assert!(pending.await.is_err()); - } - #[tokio::test] async fn a_container_importer_keeps_the_origin_failure_after_other_owners_are_released() { let (origin, completion, trigger) = crate::ffi::panicking_origin(); let mut publish = Publish::default(); - let (_publication, broadcast) = publish - .create_publication((origin.create_broadcast("retained").unwrap(), completion.clone())) + let route = origin + .route("retained", moq_net::origin::RouteOptions::hidden()) .unwrap(); + let broadcast = publish.create((route.broadcast().clone(), completion.clone())).unwrap(); let container = publish .container( broadcast, @@ -1763,9 +1650,12 @@ mod supervision_tests { async fn a_finish_after_a_driver_panic_reports_it_until_the_close() { let (origin, completion, trigger) = crate::ffi::panicking_origin(); let mut state = State::new(); - let (_publication, broadcast) = state + let route = origin + .route("retained", moq_net::origin::RouteOptions::hidden()) + .unwrap(); + let broadcast = state .publish - .create_publication((origin.create_broadcast("retained").unwrap(), completion.clone())) + .create((route.broadcast().clone(), completion.clone())) .unwrap(); let producer = &state.publish.broadcast(broadcast).unwrap().producer; // A dynamic handle outlives the consumed broadcast, so only an explicit close ends it. diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index f999572ba69..97f72e72e86 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -41,21 +41,46 @@ fn id(raw: i32) -> u32 { raw as u32 } -/// Create a broadcast at `path` on `origin`, returning its publication and fill handles. -fn create_broadcast(origin: u32, path: &[u8]) -> (u32, u32) { - let mut broadcast = 0; - let publication = - id(unsafe { moq_origin_create_broadcast(origin, path.as_ptr() as *const c_char, path.len(), &mut broadcast) }); - (publication, broadcast) +/// Create a route at `path` on `origin`, returning its route and broadcast fill handles. +fn create_route(origin: u32, path: &[u8], options: Option<&moq_route_options>) -> (u32, u32) { + let options = options.map_or(std::ptr::null(), |options| options as *const _); + let route = id(unsafe { moq_origin_route(origin, path.as_ptr() as *const c_char, path.len(), options) }); + (route, id(moq_route_broadcast(route))) } -/// Create a broadcast at `path` on `origin` and announce it, keeping only the fill handle: -/// releasing the publication leaves the route up. +/// Create a visible route at `path` on `origin`, keeping only the fill handle. The route handle +/// stays registered for the rest of the test process, so the path stays announced until the +/// broadcast closes. fn publish_broadcast(origin: u32, path: &[u8]) -> u32 { - let (publication, broadcast) = create_broadcast(origin, path); - assert_eq!(unsafe { moq_publication_announce(publication, std::ptr::null()) }, 0); - assert_eq!(moq_publication_free(publication), 0); - broadcast + create_route(origin, path, None).1 +} + +/// Route options at `cost` under the stable `instance`, borrowing it. +fn route_options(cost: u64, instance: &str, hidden: bool) -> moq_route_options { + moq_route_options { + cost, + instance: instance.as_ptr().cast(), + instance_len: instance.len(), + epoch: 0, + hidden, + } +} + +/// Default route options, created hidden. +fn hidden() -> moq_route_options { + route_options(0, "", true) +} + +/// The instance a route serves. +fn instance_of(route: u32) -> String { + let mut dst = moq_string { + data: std::ptr::null(), + len: 0, + }; + assert_eq!(unsafe { moq_route_instance(route, &mut dst) }, 0); + unsafe { std::str::from_utf8(std::slice::from_raw_parts(dst.data.cast::(), dst.len)) } + .unwrap() + .to_string() } /// Request a published broadcast via `moq_origin_request` and return its handle. @@ -166,7 +191,7 @@ fn announce_info(announced: u32) -> moq_announce_event { captures: std::ptr::null(), captures_len: 0, kind: moq_announce_kind::MOQ_ANNOUNCE_KIND_PRESENT, - route: moq_route { + route: moq_route_info { hops: std::ptr::null(), hops_len: 0, cost: 0, @@ -185,18 +210,8 @@ fn fresh_instance() -> String { moq_net::Instance::random().to_string() } -/// An announce route at `cost` under the stable `instance`, borrowing it. -fn announce_route(cost: u64, instance: &str) -> moq_announce_route { - moq_announce_route { - cost, - instance: instance.as_ptr().cast(), - instance_len: instance.len(), - epoch: 0, - } -} - /// The instance a received route carries. -fn route_instance(route: &moq_route) -> Option { +fn route_instance(route: &moq_route_info) -> Option { (route.instance.len > 0).then(|| unsafe { std::str::from_utf8(std::slice::from_raw_parts( route.instance.data.cast::(), @@ -3842,75 +3857,91 @@ fn announced_deactivation() { let announced_task = id(unsafe { moq_origin_announced(origin, std::ptr::null(), Some(channel_callback), cb.ptr) }); let path = b"deactivate/test"; - let (publication, broadcast) = create_broadcast(origin, path); - assert_eq!(unsafe { moq_publication_announce(publication, std::ptr::null()) }, 0); + let (route, broadcast) = create_route(origin, path, None); + let instance = instance_of(route); let (announced_id, info) = cb.recv_route(); assert_eq!(info.kind, moq_announce_kind::MOQ_ANNOUNCE_KIND_PRESENT); + assert_eq!(route_instance(&info.route).as_ref(), Some(&instance)); assert_eq!(moq_origin_announced_free(announced_id), 0); - // Going non-live unannounces the broadcast without tearing it down: local - // consumers stop reaching it, exactly as peers do, until it announces again. - assert_eq!(moq_publication_unannounce(publication), 0); + // Withdrawing hides the route without tearing down its broadcast: local consumers stop + // reaching it, exactly as peers do, until it announces again. + assert_eq!(moq_route_withdraw(route), 0); let (deactivated_id, info) = cb.recv_route(); assert_eq!(info.kind, moq_announce_kind::MOQ_ANNOUNCE_KIND_ABSENT); assert_eq!(moq_origin_announced_free(deactivated_id), 0); - assert!(request_once(origin, path) < 0, "an unannounced broadcast is unroutable"); + assert!(request_once(origin, path) < 0, "a withdrawn broadcast is unroutable"); - assert_eq!(unsafe { moq_publication_announce(publication, std::ptr::null()) }, 0); + // Announcing again continues the same stream. + assert_eq!(moq_route_announce(route), 0); let (reannounced_id, info) = cb.recv_route(); assert_eq!(info.kind, moq_announce_kind::MOQ_ANNOUNCE_KIND_PRESENT); + assert_eq!(route_instance(&info.route), Some(instance)); assert_eq!(moq_origin_announced_free(reannounced_id), 0); let _ = request_broadcast(origin, path); assert_eq!(moq_origin_announced_cancel(announced_task), 0); assert_eq!(cb.recv_terminal(), 0, "announced close delivers terminal 0"); assert_eq!(moq_publish_close(broadcast), 0); - assert!( - unsafe { moq_publication_announce(publication, std::ptr::null()) } < 0, - "a closed broadcast cannot announce" - ); - assert_eq!(moq_publication_free(publication), 0); - assert!(moq_publication_free(publication) < 0, "a freed publication is released"); + assert!(moq_route_announce(route) < 0, "a closed broadcast cannot announce"); + assert!(moq_route_broadcast(route) < 0, "a closed broadcast leaves the route"); + assert_eq!(moq_route_free(route), 0); + assert!(moq_route_free(route) < 0, "a freed route is released"); assert_eq!(moq_origin_close(origin), 0); } -/// A publication outliving its closed broadcast cannot announce or withdraw the broadcast that +/// Freeing the route retracts it, though its broadcast handle stays the caller's to close. +#[test] +fn freeing_a_route_retracts_it() { + let origin = id(moq_origin_create()); + let path = b"freed"; + let (route, broadcast) = create_route(origin, path, None); + let _ = request_broadcast(origin, path); + + assert_eq!(moq_route_free(route), 0); + assert!(request_once(origin, path) < 0, "a freed route is unroutable"); + assert!(moq_route_announce(route) < 0, "a freed route is released"); + let track = b"data"; + assert!(unsafe { moq_publish_track(broadcast, track.as_ptr().cast(), track.len(), std::ptr::null()) } > 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +/// A route outliving its closed broadcast cannot announce, re-price, or withdraw the route that /// replaced it at the same path. #[test] -fn a_stale_publication_leaves_its_replacement_alone() { +fn a_closed_route_leaves_its_replacement_alone() { let origin = id(moq_origin_create()); let path = b"replaced"; - let (stale, broadcast) = create_broadcast(origin, path); - assert_eq!(unsafe { moq_publication_announce(stale, std::ptr::null()) }, 0); + let (stale, broadcast) = create_route(origin, path, None); assert_eq!(moq_publish_close(broadcast), 0); - let (publication, replacement) = create_broadcast(origin, path); - assert_eq!(unsafe { moq_publication_announce(publication, std::ptr::null()) }, 0); - assert!(unsafe { moq_publication_announce(stale, std::ptr::null()) } < 0); - assert!(moq_publication_unannounce(stale) < 0); + let (route, replacement) = create_route(origin, path, None); + assert!(moq_route_announce(stale) < 0); + assert!(moq_route_set_cost(stale, 1) < 0); + assert_eq!(moq_route_withdraw(stale), 0); let _ = request_broadcast(origin, path); - assert_eq!(moq_publication_free(stale), 0); - assert_eq!(moq_publication_free(publication), 0); + assert_eq!(moq_route_free(stale), 0); + assert_eq!(moq_route_free(route), 0); assert_eq!(moq_publish_close(replacement), 0); assert_eq!(moq_origin_close(origin), 0); } #[test] -fn create_broadcast_is_unroutable_until_announced() { +fn a_hidden_route_is_unroutable_until_announced() { let origin = id(moq_origin_create()); let cb = Callback::new(); let announced_task = id(unsafe { moq_origin_announced(origin, std::ptr::null(), Some(channel_callback), cb.ptr) }); let path = b"quiet"; - let (publication, broadcast) = create_broadcast(origin, path); + let (route, broadcast) = create_route(origin, path, Some(&hidden())); // Nobody reaches it, locally included, until it announces. - assert!(request_once(origin, path) < 0, "an unannounced broadcast is unroutable"); + assert!(request_once(origin, path) < 0, "a hidden route is unroutable"); - assert_eq!(unsafe { moq_publication_announce(publication, std::ptr::null()) }, 0); - assert_eq!(moq_publication_free(publication), 0); + assert_eq!(moq_route_announce(route), 0); let _ = request_broadcast(origin, path); let (announced_id, info) = cb.recv_route(); assert_eq!(info.kind, moq_announce_kind::MOQ_ANNOUNCE_KIND_PRESENT); @@ -3918,6 +3949,7 @@ fn create_broadcast_is_unroutable_until_announced() { assert_eq!(moq_origin_announced_cancel(announced_task), 0); assert_eq!(cb.recv_terminal(), 0); + assert_eq!(moq_route_free(route), 0); assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(moq_origin_close(origin), 0); } @@ -3925,15 +3957,14 @@ fn create_broadcast_is_unroutable_until_announced() { /// A locally announced route carries its cost and instance, and no hops: the hop chain is /// the origin's to build. #[test] -fn announce_route_carries_cost_and_instance_without_hops() { +fn route_options_carry_cost_and_instance_without_hops() { let origin = id(moq_origin_create()); let cb = Callback::new(); let announced_task = id(unsafe { moq_origin_announced(origin, std::ptr::null(), Some(channel_callback), cb.ptr) }); - let (publication, broadcast) = create_broadcast(origin, b"routed"); let instance = fresh_instance(); - let route = announce_route(7, &instance); - assert_eq!(unsafe { moq_publication_announce(publication, &route) }, 0); + let (route, broadcast) = create_route(origin, b"routed", Some(&route_options(7, &instance, false))); + assert_eq!(instance_of(route), instance); let (announced, info) = cb.recv_route(); assert_eq!(info.kind, moq_announce_kind::MOQ_ANNOUNCE_KIND_PRESENT); @@ -3942,37 +3973,46 @@ fn announce_route_carries_cost_and_instance_without_hops() { assert_eq!(route_instance(&info.route).as_ref(), Some(&instance)); assert_eq!(moq_origin_announced_free(announced), 0); - // A zeroed route is the default: cost 0 and the instance the publication minted. - let zeroed = moq_announce_route { - cost: 0, - instance: std::ptr::null(), - instance_len: 0, - epoch: 0, - }; - let (publication2, broadcast2) = create_broadcast(origin, b"plain"); - assert_eq!(unsafe { moq_publication_announce(publication2, &zeroed) }, 0); + // Re-pricing changes the route in place: the listing never reports it, but a fresh + // listing reads the new price under the same instance. + assert_eq!(moq_route_set_cost(route, 3), 0); + let repriced_cb = Callback::new(); + let repriced_task = + id(unsafe { moq_origin_announced(origin, std::ptr::null(), Some(channel_callback), repriced_cb.ptr) }); + let (announced, info) = repriced_cb.recv_route(); + assert_eq!(info.kind, moq_announce_kind::MOQ_ANNOUNCE_KIND_PRESENT); + assert_eq!(info.route.cost, 3); + assert_eq!(route_instance(&info.route).as_ref(), Some(&instance)); + assert_eq!(moq_origin_announced_free(announced), 0); + assert_eq!(moq_origin_announced_cancel(repriced_task), 0); + assert_eq!(repriced_cb.recv_announce_terminal(), 0); + + // Zeroed options are the default: visible at once, cost 0, under a freshly minted instance. + let zeroed = route_options(0, "", false); + let (plain, broadcast2) = create_route(origin, b"plain", Some(&zeroed)); let (announced, info) = cb.recv_route(); assert_eq!(info.route.cost, 0); - assert!(route_instance(&info.route).is_some_and(|minted| minted != instance)); + let minted = route_instance(&info.route).unwrap(); + assert_ne!(minted, instance); + assert_eq!(minted, instance_of(plain)); assert_eq!(moq_origin_announced_free(announced), 0); assert_eq!(moq_origin_announced_cancel(announced_task), 0); assert_eq!(cb.recv_announce_terminal(), 0); - assert_eq!(moq_publication_free(publication), 0); - assert_eq!(moq_publication_free(publication2), 0); + assert_eq!(moq_route_free(route), 0); + assert_eq!(moq_route_free(plain), 0); assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(moq_publish_close(broadcast2), 0); assert_eq!(moq_origin_close(origin), 0); } -/// Announcing under another instance is another stream: the path stays listed, and a follower -/// is handed the new instance's broadcast. +/// Another route at a path is another stream: the path stays listed, and a follower is +/// handed the new route's broadcast. #[test] -fn announce_under_a_new_instance_restarts() { +fn a_new_route_at_a_path_restarts() { let origin = id(moq_origin_create()); let cb = Callback::new(); let announced_task = id(unsafe { moq_origin_announced(origin, std::ptr::null(), Some(channel_callback), cb.ptr) }); - let (publication, broadcast) = create_broadcast(origin, b"restarted"); let follow_cb = Callback::new(); let path = b"restarted"; let follow = id(unsafe { @@ -3988,10 +4028,7 @@ fn announce_under_a_new_instance_restarts() { }); let first = fresh_instance(); - assert_eq!( - unsafe { moq_publication_announce(publication, &announce_route(0, &first)) }, - 0 - ); + let (first_route, first_broadcast) = create_route(origin, b"restarted", Some(&route_options(0, &first, false))); let (announced, info) = cb.recv_route(); assert_eq!(info.kind, moq_announce_kind::MOQ_ANNOUNCE_KIND_PRESENT); assert_eq!(route_instance(&info.route), Some(first)); @@ -3999,10 +4036,7 @@ fn announce_under_a_new_instance_restarts() { let old = id(follow_cb.recv()); let second = fresh_instance(); - assert_eq!( - unsafe { moq_publication_announce(publication, &announce_route(0, &second)) }, - 0 - ); + let (second_route, second_broadcast) = create_route(origin, b"restarted", Some(&route_options(0, &second, false))); let new = id(follow_cb.recv()); assert_ne!(old, new); @@ -4013,25 +4047,33 @@ fn announce_under_a_new_instance_restarts() { // The path stayed present throughout: the cancel's terminal is the next callback. assert_eq!(moq_origin_announced_cancel(announced_task), 0); assert_eq!(cb.recv(), 0, "a restart is not listed"); - assert_eq!(moq_publication_free(publication), 0); - assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_route_free(first_route), 0); + assert_eq!(moq_route_free(second_route), 0); + assert_eq!(moq_publish_close(first_broadcast), 0); + assert_eq!(moq_publish_close(second_broadcast), 0); assert_eq!(moq_origin_close(origin), 0); } -#[test] -fn dynamic_serves_a_request_under_a_prefix() { - let origin = id(moq_origin_create()); - let cb = Callback::new(); - let prefix = b"live"; - let dynamic = id(unsafe { - moq_origin_requests( +/// Create a prefix route over `prefix` delivering its requests through `cb`. +fn route_prefix(origin: u32, prefix: &[u8], cb: &Callback) -> u32 { + id(unsafe { + moq_origin_route_prefix( origin, prefix.as_ptr() as *const c_char, prefix.len(), + std::ptr::null(), Some(channel_callback), cb.ptr, ) - }); + }) +} + +#[test] +fn dynamic_serves_a_request_under_a_prefix() { + let origin = id(moq_origin_create()); + let cb = Callback::new(); + let dynamic = route_prefix(origin, b"live", &cb); + assert!(moq_route_broadcast(dynamic) < 0, "a prefix route owns no broadcast"); let path = b"live/cam"; let req_cb = Callback::new(); @@ -4056,17 +4098,35 @@ fn dynamic_serves_a_request_under_a_prefix() { let got = unsafe { std::str::from_utf8(std::slice::from_raw_parts(info.data.cast::(), info.len)).unwrap() }; assert_eq!(got, "live/cam"); - let mut served = 0; - let prepared = id(unsafe { moq_broadcast_request_prepare(request, &mut served) }); - let publication = id(moq_broadcast_prepared_publish(prepared)); + // Unreadable options leave the request to answer. + let invalid = [0xff]; + let unreadable = moq_route_options { + instance: invalid.as_ptr().cast(), + instance_len: invalid.len(), + ..hidden() + }; + assert_eq!( + unsafe { moq_broadcast_request_route(request, &unreadable) }, + crate::error::MOQ_ERROR_UTF8 + ); + + // A hidden job route answers nobody until it announces, under its own fresh instance. + let job = id(unsafe { moq_broadcast_request_route(request, &hidden()) }); + assert!( + unsafe { moq_broadcast_request_route(request, std::ptr::null()) } < 0, + "request is consumed" + ); + assert_ne!(instance_of(job), instance_of(dynamic)); + let served = id(moq_route_broadcast(job)); + assert_eq!(moq_route_announce(job), 0); assert!(req_cb.recv() > 0); req_cb.recv_terminal(); - // The answer's route is the publication's to withdraw. - assert_eq!(moq_publication_unannounce(publication), 0); - assert_eq!(moq_publication_free(publication), 0); + // The answer's route is the job's to withdraw. + assert_eq!(moq_route_withdraw(job), 0); + assert_eq!(moq_route_free(job), 0); - assert_eq!(moq_origin_requests_cancel(dynamic), 0); - assert!(moq_origin_requests_cancel(dynamic) < 0, "double-cancel should fail"); + assert_eq!(moq_route_free(dynamic), 0); + assert!(moq_route_free(dynamic) < 0, "double-free should fail"); assert_eq!(cb.recv_terminal(), 0); assert_eq!(moq_publish_close(served), 0); assert_eq!(moq_origin_close(origin), 0); @@ -4078,8 +4138,7 @@ fn dynamic_serves_a_held_consumer_without_taking_its_handle() { let broadcast = publish_broadcast(origin, b"source"); let held = consume_local(broadcast); let cb = Callback::new(); - let dynamic = - id(unsafe { moq_origin_requests(origin, b"live".as_ptr().cast(), 4, Some(channel_callback), cb.ptr) }); + let dynamic = route_prefix(origin, b"live", &cb); let result = Callback::new(); let _task = id(unsafe { moq_origin_request( @@ -4099,7 +4158,7 @@ fn dynamic_serves_a_held_consumer_without_taking_its_handle() { assert_eq!(moq_consume_close(held), 0, "source handle remains caller-owned"); result.recv_terminal(); assert_eq!(moq_consume_close(served), 0); - assert_eq!(moq_origin_requests_cancel(dynamic), 0); + assert_eq!(moq_route_free(dynamic), 0); cb.recv_terminal(); assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(moq_origin_close(origin), 0); @@ -4110,10 +4169,11 @@ fn dynamic_refuses_a_missing_callback() { let origin = id(moq_origin_create()); let prefix = b"live"; let code = unsafe { - moq_origin_requests( + moq_origin_route_prefix( origin, prefix.as_ptr() as *const c_char, prefix.len(), + std::ptr::null(), None, std::ptr::null_mut(), ) @@ -5123,16 +5183,16 @@ fn follow_close_cancels() { assert_eq!(moq_origin_close(origin), 0); } -/// Publish `path` on `origin` through `route` from Rust, keeping the Rust publication. -fn publish(origin: u32, path: &str, route: moq_net::origin::Route) -> moq_net::origin::Publication { +/// Route `path` on `origin` with `options` from Rust, keeping the Rust route. +fn publish(origin: u32, path: &str, options: moq_net::origin::RouteOptions) -> moq_net::origin::Route { let _runtime = crate::ffi::RUNTIME.enter(); let origin = crate::Id::try_from(origin).unwrap(); - State::lock().origin.get(origin).unwrap().publish(path, route).unwrap() + State::lock().origin.get(origin).unwrap().route(path, options).unwrap() } -/// Publish `path` on `origin` under a fresh instance, as each run of a publisher does. -fn publish_run(origin: u32, path: &str) -> moq_net::origin::Publication { - publish(origin, path, moq_net::origin::Route::default()) +/// Route `path` on `origin` under a fresh instance, as each run of a publisher does. +fn publish_run(origin: u32, path: &str) -> moq_net::origin::Route { + publish(origin, path, moq_net::origin::RouteOptions::default()) } /// Another publisher instance taking the path delivers a fresh handle on the same wait. @@ -5176,7 +5236,12 @@ fn follow_delivers_a_takeover_once(dynamic_at: &str) { let dynamic = { let _runtime = crate::ffi::RUNTIME.enter(); let origin = crate::Id::try_from(origin).unwrap(); - State::lock().origin.get(origin).unwrap().requests(dynamic_at).unwrap() + State::lock() + .origin + .get(origin) + .unwrap() + .route_prefix(dynamic_at, moq_net::origin::RouteOptions::default()) + .unwrap() }; let cb = Callback::new(); let path = b"live"; @@ -5193,8 +5258,8 @@ fn follow_delivers_a_takeover_once(dynamic_at: &str) { }); // The wait is on the dynamic route's answer when the exact path takes over under another instance. - let _unanswered = crate::ffi::RUNTIME.block_on(dynamic.requested_broadcast()).unwrap(); - let takeover = publish(origin, "live", moq_net::origin::Route::default()); + let _unanswered = crate::ffi::RUNTIME.block_on(dynamic.requested()).unwrap(); + let takeover = publish_run(origin, "live"); let delivered = id(cb.recv()); assert!( cb.rx @@ -5256,7 +5321,7 @@ fn an_instance_pins_request_and_follow() { let first = publish( origin, "live", - moq_net::origin::Route::default().with_instance(instance.clone(), 0), + moq_net::origin::RouteOptions::default().with_instance(instance.clone(), 0), ); let instance = instance.to_string(); @@ -5304,10 +5369,15 @@ fn an_instance_pins_request_and_follow() { } /// Serve `prefix` on `origin` dynamically. -fn serve_dynamic(origin: u32, prefix: &str) -> moq_net::origin::Requests { +fn serve_dynamic(origin: u32, prefix: &str) -> moq_net::origin::Route { let _runtime = crate::ffi::RUNTIME.enter(); let origin = crate::Id::try_from(origin).unwrap(); - State::lock().origin.get(origin).unwrap().requests(prefix).unwrap() + State::lock() + .origin + .get(origin) + .unwrap() + .route_prefix(prefix, moq_net::origin::RouteOptions::default()) + .unwrap() } /// Wait for the broadcast at `path` on `origin`, delivering each instance through `cb`. @@ -5374,16 +5444,16 @@ fn follow_delivers_the_instance_again_after_an_end() { }); let recv = || rx.recv_timeout(TIMEOUT).expect("callback timed out"); - let route = moq_net::origin::Route::default().with_instance(moq_net::Instance::random(), 0); - let run = publish(origin, "live", route.clone()); + let options = moq_net::origin::RouteOptions::default().with_instance(moq_net::Instance::random(), 0); + let run = publish(origin, "live", options); let first = id(recv()); // Hold the wait inside that delivery so both changes are on hand when it next looks: the // same stream announcing again after its route left is still a gap. { let _runtime = crate::ffi::RUNTIME.enter(); - run.unannounce(); - run.announce(route.clone()).unwrap(); + run.withdraw(); + run.announce().unwrap(); } release.send(()).unwrap(); assert_eq!(recv(), FOLLOW_OFFLINE, "the gap is reported before the return"); @@ -5407,7 +5477,7 @@ fn follow_waits_for_another_instance_after_a_freed_takeover() { let cb = Callback::new(); let task = follow(origin, b"live", &cb); - let _unanswered = crate::ffi::RUNTIME.block_on(dynamic.requested_broadcast()).unwrap(); + let _unanswered = crate::ffi::RUNTIME.block_on(dynamic.requested()).unwrap(); let takeover = publish_run(origin, "live"); assert_eq!(moq_consume_close(id(cb.recv())), 0); assert!( @@ -5435,7 +5505,7 @@ fn follow_delivers_a_gap_while_resolving_once() { let cb = Callback::new(); let task = follow(origin, b"live", &cb); - let _unanswered = crate::ffi::RUNTIME.block_on(dynamic.requested_broadcast()).unwrap(); + let _unanswered = crate::ffi::RUNTIME.block_on(dynamic.requested()).unwrap(); { let _runtime = crate::ffi::RUNTIME.enter(); drop(dynamic); @@ -5445,7 +5515,7 @@ fn follow_delivers_a_gap_while_resolving_once() { reason = "the test thread has no runtime; it waits out the hold on the C API's real runtime" )] std::thread::sleep(moq_net::origin::Config::default().update_hold * 2); - let arrival = publish(origin, "live", moq_net::origin::Route::default()); + let arrival = publish_run(origin, "live"); let delivered = id(cb.recv()); assert!( cb.rx @@ -7665,14 +7735,7 @@ fn announce_route_hops_cross_a_relay_session() { let announced_cb = Callback::new(); let task = id(unsafe { moq_origin_announced(sink, std::ptr::null(), Some(channel_callback), announced_cb.ptr) }); - let (publication, broadcast) = create_broadcast(source, b"relayed"); - let route = moq_announce_route { - cost: 7, - instance: std::ptr::null(), - instance_len: 0, - epoch: 0, - }; - assert_eq!(unsafe { moq_publication_announce(publication, &route) }, 0); + let (route, broadcast) = create_route(source, b"relayed", Some(&route_options(7, "", false))); let (announced, info) = announced_cb.recv_route(); assert_eq!(info.kind, moq_announce_kind::MOQ_ANNOUNCE_KIND_PRESENT); assert_eq!( @@ -7701,7 +7764,7 @@ fn announce_route_hops_cross_a_relay_session() { } assert_eq!(moq_server_close(server), 0); assert_eq!(server_cb.recv_terminal(), 0); - assert_eq!(moq_publication_free(publication), 0); + assert_eq!(moq_route_free(route), 0); assert_eq!(moq_publish_close(broadcast), 0); for origin in [source, relay, sink] { assert_eq!(moq_origin_close(origin), 0); diff --git a/rs/moq-cli/src/announced.rs b/rs/moq-cli/src/announced.rs index c46d412f25f..ac9ed23d9c9 100644 --- a/rs/moq-cli/src/announced.rs +++ b/rs/moq-cli/src/announced.rs @@ -181,7 +181,7 @@ mod tests { /// Stops the relay, which ends every session on it. shutdown: moq_relay::shutdown::Trigger, /// The published broadcasts by path; dropping one retracts it. - broadcasts: Vec<(&'static str, moq_net::origin::Publication)>, + broadcasts: Vec<(&'static str, moq_net::origin::Route)>, _publisher: moq_tokio::Connection, } @@ -206,8 +206,9 @@ mod tests { let broadcasts = ["demo/a", "demo/b", "other/c"] .into_iter() .map(|path| { - let broadcast = origin.create_broadcast(path).expect("broadcast"); - broadcast.announce(Default::default()).expect("announce"); + let broadcast = origin + .route(path, moq_net::origin::RouteOptions::default()) + .expect("broadcast"); (path, broadcast) }) .collect::>(); diff --git a/rs/moq-cli/src/archive.rs b/rs/moq-cli/src/archive.rs index a0b71ccfa03..e161286e163 100644 --- a/rs/moq-cli/src/archive.rs +++ b/rs/moq-cli/src/archive.rs @@ -296,13 +296,17 @@ pub async fn import( if let Some(refresh) = args.refresh { config = config.with_refresh(refresh.into()); } - let broadcast = origin.create_broadcast(&name).context("failed to create broadcast")?; - let consumer = moq_archive::Consumer::open(store, broadcast.broadcast().clone(), config) + // Hidden until the recording opens, then held while the replay runs. + let route = origin + .route( + &name, + moq_net::origin::RouteOptions::hidden().with_instance(instance, 0), + ) + .context("failed to create broadcast")?; + let consumer = moq_archive::Consumer::open(store, route.broadcast().clone(), config) .await .with_context(|| format!("no readable recording at {}", args.store))?; - broadcast - .announce(moq_net::origin::Route::default().with_instance(instance, 0)) - .context("failed to announce broadcast")?; + route.announce().context("failed to announce broadcast")?; tracing::info!(%name, store = %args.store, "replaying"); notify_ready(); @@ -400,16 +404,13 @@ mod tests { let mut instances = Vec::new(); let mut broadcasts = Vec::new(); for path in ["live/a", "live/b", "other"] { - let broadcast = origin.create_broadcast(path).unwrap(); - let track = broadcast.create_track("video", info.clone()).unwrap(); + let broadcast = origin.route(path, moq_net::origin::RouteOptions::hidden()).unwrap(); + let track = broadcast.broadcast().create_track("video", info.clone()).unwrap(); let mut group = track.create_group(group::Info { sequence: 0 }).unwrap(); group.write_frame(Timestamp::from_millis(0).unwrap(), path).unwrap(); group.finish().unwrap(); - let instance = moq_net::Instance::random(); - broadcast - .announce(moq_net::origin::Route::default().with_instance(instance.clone(), 0)) - .unwrap(); - instances.push(instance); + broadcast.announce().unwrap(); + instances.push(broadcast.instance()); broadcasts.push((broadcast, track)); } @@ -420,7 +421,7 @@ mod tests { .expect("the export subscribes") .unwrap(); track.finish().unwrap(); - broadcast.close(); + broadcast.broadcast().close(); } let complete = [ format!("live/a/@{}/.end", instances[0]), @@ -460,10 +461,12 @@ mod tests { retention_grace: None, }; let origin = moq_tokio::origin::spawn(); - let claim = origin.requests("live/a").unwrap(); + let claim = origin + .route_prefix("live/a", moq_net::origin::RouteOptions::default()) + .unwrap(); let recording = tokio::spawn(export(origin.consume(), "live".into(), args)); - let request = kio::clock::timeout(Duration::from_secs(10), claim.requested_broadcast()) + let request = kio::clock::timeout(Duration::from_secs(10), claim.requested()) .await .expect("the export follows the listed path") .unwrap(); @@ -522,7 +525,7 @@ mod tests { loop { if let Some(moq_net::announce::Event::Present(announce)) = announced.next().await { assert_eq!(announce.prefix.as_str(), "replay"); - assert_eq!(announce.route.instance, Some(instance.clone())); + assert_eq!(announce.route.instance(), &instance); break; } } @@ -555,16 +558,18 @@ mod tests { async fn a_resolved_broadcast_is_recorded_once() { let origin = moq_tokio::origin::spawn(); let path = moq_net::Path::from_static("live/a"); - let newest = origin.create_broadcast(&path).unwrap(); - let older = origin.create_broadcast(&path).unwrap(); + let newest = origin.route(&path, moq_net::origin::RouteOptions::hidden()).unwrap(); + let older = origin.route(&path, moq_net::origin::RouteOptions::hidden()).unwrap(); let claims = Claims::default(); - let claim = claims.claim(&path, &newest.consume()).expect("first claim"); - assert!(claims.claim(&path, &newest.consume()).is_none()); - let beside = claims.claim(&path, &older.consume()).expect("another instance"); + let claim = claims.claim(&path, &newest.broadcast().consume()).expect("first claim"); + assert!(claims.claim(&path, &newest.broadcast().consume()).is_none()); + let beside = claims + .claim(&path, &older.broadcast().consume()) + .expect("another instance"); drop(claim); - assert!(claims.claim(&path, &newest.consume()).is_some()); + assert!(claims.claim(&path, &newest.broadcast().consume()).is_some()); drop(beside); assert!(claims.0.lock().unwrap().is_empty()); } diff --git a/rs/moq-cli/src/complete.rs b/rs/moq-cli/src/complete.rs index 02891375b99..f43b36da713 100644 --- a/rs/moq-cli/src/complete.rs +++ b/rs/moq-cli/src/complete.rs @@ -428,8 +428,7 @@ mod tests { moq_tokio::crypto::install_default().unwrap(); let origin = moq_tokio::origin::spawn(); - let _alpha = origin.create_broadcast("alpha").expect("alpha"); - _alpha.announce(Default::default()).expect("alpha"); + let _alpha = origin.route("alpha", Default::default()).expect("alpha"); let mut config = moq_tokio::listen::Config::default(); config.bind = Some("127.0.0.1:0".parse().unwrap()); diff --git a/rs/moq-cli/src/fetch.rs b/rs/moq-cli/src/fetch.rs index 9f9c16c2412..23420c51dae 100644 --- a/rs/moq-cli/src/fetch.rs +++ b/rs/moq-cli/src/fetch.rs @@ -187,7 +187,7 @@ mod tests { struct Fixture { origin: moq_net::origin::Producer, _keep: ( - moq_net::origin::Publication, + moq_net::origin::Route, Vec, moq_net::group::Producer, ), @@ -196,10 +196,11 @@ mod tests { impl Fixture { async fn new() -> Self { let origin = moq_tokio::origin::spawn(); - let broadcast = origin.create_broadcast("demo").expect("broadcast"); - broadcast.announce(Default::default()).expect("announce"); + let broadcast = origin + .route("demo", moq_net::origin::RouteOptions::default()) + .expect("broadcast"); - let data = broadcast.create_track("data", timed()).expect("data track"); + let data = broadcast.broadcast().create_track("data", timed()).expect("data track"); for sequence in 0..3 { let mut group = data.append_group().expect("group"); for frame in frames(sequence) { @@ -207,8 +208,11 @@ mod tests { } group.finish().expect("finish"); } - let empty = broadcast.create_track("empty", timed()).expect("empty track"); - let live = broadcast.create_track("live", timed()).expect("live track"); + let empty = broadcast + .broadcast() + .create_track("empty", timed()) + .expect("empty track"); + let live = broadcast.broadcast().create_track("live", timed()).expect("live track"); let mut open = live.append_group().expect("open group"); open.write_frame(moq_net::Timestamp::ZERO, b"first".as_ref()) .expect("frame"); @@ -245,7 +249,7 @@ mod tests { /// Kept so the published broadcast, its tracks, and the open group stay live. _publisher: (moq_tokio::Connection, Fixture), /// Kept so the relay's hidden broadcast and its track stay live. - _hidden: (moq_net::origin::Publication, moq_net::track::Producer), + _hidden: (moq_net::origin::Route, moq_net::track::Producer), } impl NetworkFixture { @@ -259,10 +263,9 @@ mod tests { .relay .cluster() .origin - .create_broadcast(".hidden") + .route(".hidden", moq_net::origin::RouteOptions::default()) .expect("hidden broadcast"); - hidden.announce(Default::default()).expect("announce hidden"); - let secret = hidden.create_track("data", timed()).expect("hidden track"); + let secret = hidden.broadcast().create_track("data", timed()).expect("hidden track"); let mut group = secret.append_group().expect("group"); group .write_frame(moq_net::Timestamp::ZERO, b"secret".as_ref()) diff --git a/rs/moq-cli/src/hls.rs b/rs/moq-cli/src/hls.rs index e4c1a40b785..5b79d9a61c5 100644 --- a/rs/moq-cli/src/hls.rs +++ b/rs/moq-cli/src/hls.rs @@ -170,12 +170,18 @@ pub async fn import(target: ImportTarget, args: ImportArgs, instance: moq_net::I linger, bandwidth, } = target; - let producer = origin.create_broadcast(&name).context("failed to create broadcast")?; + // Held through the linger, so the finished broadcast stays announced while it serves the tail. + let route = origin + .route( + &name, + moq_net::origin::RouteOptions::hidden().with_instance(instance, 0), + ) + .context("failed to create broadcast")?; let config = moq_mux::catalog::Config::default() .with_max_age(max_age) .with_bandwidth(bandwidth); - let catalog = moq_mux::catalog::Producer::new(&mut producer.broadcast().clone(), config)?; + let catalog = moq_mux::catalog::Producer::new(&mut route.broadcast().clone(), config)?; // Announced once the catalog first goes out, which waits for every rendition's init: a // relay queries a broadcast's tracks the moment it is announced, and keeps the refusals of a // publisher that cannot serve its declared tracks yet. @@ -183,14 +189,14 @@ pub async fn import(target: ImportTarget, args: ImportArgs, instance: moq_net::I let mut config = moq_hls::import::Config::new(playlist_url(&args.playlist)?); config.passthrough = args.passthrough; - let mut importer = moq_hls::import::Import::new(producer.broadcast().clone(), catalog, config)?; + let mut importer = moq_hls::import::Import::new(route.broadcast().clone(), catalog, config)?; tracing::info!(%name, "importing HLS"); let ran = match importer.init().await { Ok(()) => { notify_ready(); - run_announced(&mut importer, &mut listed, &producer, instance).await + run_announced(&mut importer, &mut listed, &route).await } Err(err) => Err(err.into()), }; @@ -204,7 +210,7 @@ pub async fn import(target: ImportTarget, args: ImportArgs, instance: moq_net::I // arrives after the end still gets the tail. An interrupt drops it at once. importer.finish()?; tracing::info!(?linger, "playlist ended; serving the finished broadcast"); - moq_mux::Linger::new([producer.broadcast().clone()], importer, linger) + moq_mux::Linger::new([route.broadcast().clone()], importer, linger) .wait() .await; Ok(()) @@ -216,8 +222,7 @@ pub async fn import(target: ImportTarget, args: ImportArgs, instance: moq_net::I async fn run_announced( importer: &mut moq_hls::import::Import, listed: &mut moq_mux::catalog::hang::Consumer, - publication: &moq_net::origin::Publication, - instance: moq_net::Instance, + route: &moq_net::origin::Route, ) -> anyhow::Result<()> { let run = importer.run(); tokio::pin!(run); @@ -233,9 +238,7 @@ async fn run_announced( } }; anyhow::ensure!(catalog.is_some(), "the playlist ended before it declared a track"); - publication - .announce(moq_net::origin::Route::default().with_instance(instance, 0)) - .context("failed to announce broadcast")?; + route.announce().context("failed to announce broadcast")?; if !ended { run.await?; } @@ -389,7 +392,7 @@ mod test { tempfile::TempDir, moq_hls::import::Import, moq_mux::catalog::hang::Consumer, - moq_net::origin::Publication, + moq_net::origin::Route, )> { let dir = tempfile::tempdir()?; write_playlist(dir.path(), segments, false); @@ -397,7 +400,7 @@ mod test { let (origin, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::default()); tokio::spawn(moq_net::time::run(driver)); - let producer = origin.create_broadcast("hls")?; + let producer = origin.route("hls", moq_net::origin::RouteOptions::hidden())?; let catalog = moq_mux::catalog::Producer::new(&mut producer.broadcast().clone(), moq_mux::catalog::Config::default())?; let listed = catalog.consume()?; @@ -419,10 +422,8 @@ mod test { async fn an_ended_playlist_announces_its_catalog() { for _ in 0..32 { let (_dir, mut importer, mut listed, producer) = joined_then_ended(1).await.unwrap(); - run_announced(&mut importer, &mut listed, &producer, moq_net::Instance::random()) - .await - .unwrap(); - assert!(producer.route().is_some(), "the finished playlist was not announced"); + run_announced(&mut importer, &mut listed, &producer).await.unwrap(); + assert!(producer.is_announced(), "the finished playlist was not announced"); } } @@ -440,8 +441,8 @@ mod test { #[tokio::test] async fn an_empty_playlist_fails_unannounced() { let (_dir, mut importer, mut listed, producer) = joined_then_ended(0).await.unwrap(); - let result = run_announced(&mut importer, &mut listed, &producer, moq_net::Instance::random()).await; - assert!(producer.route().is_none(), "an empty playlist was announced"); + let result = run_announced(&mut importer, &mut listed, &producer).await; + assert!(!producer.is_announced(), "an empty playlist was announced"); let err = result.expect_err("an empty playlist imports nothing"); assert!(format!("{err:#}").contains("before it declared a track"), "{err:#}"); } diff --git a/rs/moq-cli/src/hls/record.rs b/rs/moq-cli/src/hls/record.rs index 9e8f3b57e89..6b545b2d125 100644 --- a/rs/moq-cli/src/hls/record.rs +++ b/rs/moq-cli/src/hls/record.rs @@ -604,7 +604,7 @@ mod tests { /// A broadcast publishing VP8 renditions with aligned two-second GOPs. struct Publisher { origin: moq_net::origin::Producer, - broadcast: moq_net::origin::Publication, + broadcast: moq_net::origin::Route, catalog: moq_mux::catalog::Producer, video: Vec