rr.serve -> rr.serve_web, rr.connect -> rr.connect_tcp (#7906)

rerun-io · Oct 28, 2024 · 05d05bc · 05d05bc
1 parent 558ff44
commit 05d05bc
Show file tree

Hide file tree

Showing 35 changed files with 298 additions and 47 deletions.
diff --git a/crates/top/re_sdk/src/recording_stream.rs b/crates/top/re_sdk/src/recording_stream.rs
@@ -310,8 +310,24 @@ impl RecordingStreamBuilder {
     /// let rec = re_sdk::RecordingStreamBuilder::new("rerun_example_app").connect()?;
     /// # Ok::<(), Box<dyn std::error::Error>>(())
     /// ```
+    #[deprecated(since = "0.20.0", note = "use connect_tcp() instead")]
     pub fn connect(self) -> RecordingStreamResult<RecordingStream> {
-        self.connect_opts(crate::default_server_addr(), crate::default_flush_timeout())
+        self.connect_tcp()
+    }
+
+    /// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
+    /// remote Rerun instance.
+    ///
+    /// See also [`Self::connect_opts`] if you wish to configure the TCP connection.
+    ///
+    /// ## Example
+    ///
+    /// ```no_run
+    /// let rec = re_sdk::RecordingStreamBuilder::new("rerun_example_app").connect_tcp()?;
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    pub fn connect_tcp(self) -> RecordingStreamResult<RecordingStream> {
+        self.connect_tcp_opts(crate::default_server_addr(), crate::default_flush_timeout())
     }
 
     /// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
@@ -328,10 +344,33 @@ impl RecordingStreamBuilder {
     ///     .connect_opts(re_sdk::default_server_addr(), re_sdk::default_flush_timeout())?;
     /// # Ok::<(), Box<dyn std::error::Error>>(())
     /// ```
+    #[deprecated(since = "0.20.0", note = "use connect_tcp_opts() instead")]
     pub fn connect_opts(
         self,
         addr: std::net::SocketAddr,
         flush_timeout: Option<std::time::Duration>,
+    ) -> RecordingStreamResult<RecordingStream> {
+        self.connect_tcp_opts(addr, flush_timeout)
+    }
+
+    /// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
+    /// remote Rerun instance.
+    ///
+    /// `flush_timeout` is the minimum time the [`TcpSink`][`crate::log_sink::TcpSink`] will
+    /// wait during a flush before potentially dropping data. Note: Passing `None` here can cause a
+    /// call to `flush` to block indefinitely if a connection cannot be established.
+    ///
+    /// ## Example
+    ///
+    /// ```no_run
+    /// let rec = re_sdk::RecordingStreamBuilder::new("rerun_example_app")
+    ///     .connect_opts(re_sdk::default_server_addr(), re_sdk::default_flush_timeout())?;
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    pub fn connect_tcp_opts(
+        self,
+        addr: std::net::SocketAddr,
+        flush_timeout: Option<std::time::Duration>,
     ) -> RecordingStreamResult<RecordingStream> {
         let (enabled, store_info, batcher_config) = self.into_args();
         if enabled {
@@ -464,12 +503,12 @@ impl RecordingStreamBuilder {
         // NOTE: If `_RERUN_TEST_FORCE_SAVE` is set, all recording streams will write to disk no matter
         // what, thus spawning a viewer is pointless (and probably not intended).
         if forced_sink_path().is_some() {
-            return self.connect_opts(connect_addr, flush_timeout);
+            return self.connect_tcp_opts(connect_addr, flush_timeout);
         }
 
         crate::spawn(opts)?;
 
-        self.connect_opts(connect_addr, flush_timeout)
+        self.connect_tcp_opts(connect_addr, flush_timeout)
     }
 
     /// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
@@ -503,13 +542,62 @@ impl RecordingStreamBuilder {
     //
     // # TODO(#5531): keep static data around.
     #[cfg(feature = "web_viewer")]
+    #[deprecated(since = "0.20.0", note = "use serve_web() instead")]
     pub fn serve(
         self,
         bind_ip: &str,
         web_port: WebViewerServerPort,
         ws_port: RerunServerPort,
         server_memory_limit: re_memory::MemoryLimit,
         open_browser: bool,
+    ) -> RecordingStreamResult<RecordingStream> {
+        self.serve_web(
+            bind_ip,
+            web_port,
+            ws_port,
+            server_memory_limit,
+            open_browser,
+        )
+    }
+
+    /// Creates a new [`RecordingStream`] that is pre-configured to stream the data through to a
+    /// web-based Rerun viewer via WebSockets.
+    ///
+    /// If the `open_browser` argument is `true`, your default browser will be opened with a
+    /// connected web-viewer.
+    ///
+    /// If not, you can connect to this server using the `rerun` binary (`cargo install rerun-cli --locked`).
+    ///
+    /// ## Details
+    /// This method will spawn two servers: one HTTPS server serving the Rerun Web Viewer `.html` and `.wasm` files,
+    /// and then one WebSocket server that streams the log data to the web viewer (or to a native viewer, or to multiple viewers).
+    ///
+    /// The WebSocket server will buffer all log data in memory so that late connecting viewers will get all the data.
+    /// You can limit the amount of data buffered by the WebSocket server with the `server_memory_limit` argument.
+    /// Once reached, the earliest logged data will be dropped.
+    /// Note that this means that static data may be dropped if logged early (see <https://github.com/rerun-io/rerun/issues/5531>).
+    ///
+    /// ## Example
+    ///
+    /// ```ignore
+    /// let rec = re_sdk::RecordingStreamBuilder::new("rerun_example_app")
+    ///     .serve_web("0.0.0.0",
+    ///                Default::default(),
+    ///                Default::default(),
+    ///                re_sdk::MemoryLimit::from_fraction_of_total(0.25),
+    ///                true)?;
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    //
+    // # TODO(#5531): keep static data around.
+    #[cfg(feature = "web_viewer")]
+    pub fn serve_web(
+        self,
+        bind_ip: &str,
+        web_port: WebViewerServerPort,
+        ws_port: RerunServerPort,
+        server_memory_limit: re_memory::MemoryLimit,
+        open_browser: bool,
     ) -> RecordingStreamResult<RecordingStream> {
         let (enabled, store_info, batcher_config) = self.into_args();
         if enabled {

diff --git a/crates/top/rerun/src/clap.rs b/crates/top/rerun/src/clap.rs
@@ -112,7 +112,7 @@ impl RerunArgs {
 
             RerunBehavior::Connect(addr) => Ok((
                 RecordingStreamBuilder::new(application_id)
-                    .connect_opts(addr, crate::default_flush_timeout())?,
+                    .connect_tcp_opts(addr, crate::default_flush_timeout())?,
                 Default::default(),
             )),
 
@@ -132,7 +132,7 @@ impl RerunArgs {
                     .map_err(|err| anyhow::format_err!("Bad --server-memory-limit: {err}"))?;
 
                 let open_browser = true;
-                let rec = RecordingStreamBuilder::new(application_id).serve(
+                let rec = RecordingStreamBuilder::new(application_id).serve_web(
                     &self.bind,
                     Default::default(),
                     Default::default(),

diff --git a/crates/viewer/re_viewer/data/quick_start_guides/quick_start_connect.cpp b/crates/viewer/re_viewer/data/quick_start_guides/quick_start_connect.cpp
@@ -6,7 +6,7 @@ using namespace rerun::demo;
 int main() {
     // Create a new `RecordingStream` which sends data over TCP to the viewer process.
     const auto rec = rerun::RecordingStream("rerun_example_quick_start_connect");
-    rec.connect().exit_on_failure();
+    rec.connect_tcp().exit_on_failure();
 
     // Create some data using the `grid` utility function.
     std::vector<rerun::Position3D> points = grid3d<rerun::Position3D, float>(-10.f, 10.f, 10);

diff --git a/crates/viewer/re_viewer/data/quick_start_guides/quick_start_connect.py b/crates/viewer/re_viewer/data/quick_start_guides/quick_start_connect.py
@@ -7,7 +7,7 @@
 rr.init("rerun_example_quick_start_connect")
 
 # Connect to a local viewer using the default port
-rr.connect()
+rr.connect_tcp()
 
 
 # Create some data

diff --git a/crates/viewer/re_viewer/data/quick_start_guides/quick_start_connect.rs b/crates/viewer/re_viewer/data/quick_start_guides/quick_start_connect.rs
@@ -4,7 +4,8 @@ use rerun::{demo_util::grid, external::glam};
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Create a new `RecordingStream` which sends data over TCP to the viewer process.
-    let rec = rerun::RecordingStreamBuilder::new("rerun_example_quick_start_connect").connect()?;
+    let rec =
+        rerun::RecordingStreamBuilder::new("rerun_example_quick_start_connect").connect_tcp()?;
 
     // Create some data using the `grid` utility function.
     let points = grid(glam::Vec3::splat(-10.0), glam::Vec3::splat(10.0), 10);

diff --git a/docs/content/reference/migration/migration-0-13.md b/docs/content/reference/migration/migration-0-13.md
@@ -1,6 +1,6 @@
 ---
 title: Migrating from 0.12 to 0.13
-order: 130
+order: 996
 ---
 
 ## `TimeSeriesScalar` deprecated in favor of [Scalar](../types/archetypes/scalar.md) & [SeriesLine](../types/archetypes/series_line.md)/[SeriesPoint](../types/archetypes/series_point.md)

diff --git a/docs/content/reference/migration/migration-0-15.md b/docs/content/reference/migration/migration-0-15.md
@@ -1,6 +1,6 @@
 ---
 title: Migrating from 0.14 to 0.15
-order: 150
+order: 995
 ---
 
 ## `InstanceKey` removed from our logging APIs

diff --git a/docs/content/reference/migration/migration-0-16.md b/docs/content/reference/migration/migration-0-16.md
@@ -1,6 +1,6 @@
 ---
 title: Migrating from 0.15 to 0.16
-order: 160
+order: 994
 ---
 
 

diff --git a/docs/content/reference/migration/migration-0-17.md b/docs/content/reference/migration/migration-0-17.md
@@ -1,6 +1,6 @@
 ---
 title: Migrating from 0.16 to 0.17
-order: 170
+order: 993
 ---
 
 

diff --git a/docs/content/reference/migration/migration-0-18.md b/docs/content/reference/migration/migration-0-18.md
@@ -1,6 +1,6 @@
 ---
 title: Migrating from 0.17 to 0.18
-order: 180
+order: 992
 ---
 
 ## ⚠️ Breaking changes

diff --git a/docs/content/reference/migration/migration-0-19.md b/docs/content/reference/migration/migration-0-19.md
@@ -1,6 +1,6 @@
 ---
 title: Migrating from 0.18 to 0.19
-order: 190
+order: 991
 ---
 
 Blueprint files (.rbl) from previous Rerun versions will no longer load _automatically_.

diff --git a/docs/content/reference/migration/migration-0-20.md b/docs/content/reference/migration/migration-0-20.md
@@ -0,0 +1,20 @@
+---
+title: Migrating from 0.19 to 0.20
+order: 990
+---
+
+
+## ⚠️ Breaking changes
+
+
+### `connect` -> `connect_tcp` & `serve` -> `serve_web`
+
+In all SDKs:
+* `connect()` is now deprecated in favor `connect_tcp()`
+* `serve()` is now deprecated in favor `serve_web()`
+
+The rationale behind this change is that it was common for users (see https://github.com/rerun-io/rerun/issues/7766).
+
+We frequently had reports from users that were understandably expecting a serving process (`rr.serve()`) to be ready to accept connections from other processes (`rr.connect()`), when in reality the two things are completely unrelated: one is hosting a websocket server to be polled by the web-viewer, while the other is trying to connect to the TCP SDK comms pipeline.
+
+You can learn more about Rerun's application model and the different servers and ports by reading our [new documentation page on the matter](../../concepts/app-model.md).
diff --git a/docs/content/reference/migration/migration-0-9.md b/docs/content/reference/migration/migration-0-9.md
@@ -1,6 +1,6 @@
 ---
 title: Migrating from 0.8 to 0.9
-order: 90
+order: 1000
 ---
 
 Rerun-0.9 introduces a new set of type-oriented logging APIs built on top of an updated, more concrete,

diff --git a/docs/snippets/all/concepts/app-model/native-sync.cpp b/docs/snippets/all/concepts/app-model/native-sync.cpp
@@ -4,7 +4,7 @@ int main() {
     // Connect to the Rerun TCP server using the default address and
     // port: localhost:9876
     const auto rec = rerun::RecordingStream("rerun_example_native_sync");
-    rec.connect().exit_on_failure();
+    rec.connect_tcp().exit_on_failure();
 
     // Log data as usual, thereby pushing it into the TCP socket.
     while (true) {

diff --git a/docs/snippets/all/concepts/app-model/native-sync.py b/docs/snippets/all/concepts/app-model/native-sync.py
@@ -6,7 +6,7 @@
 
 # Connect to the Rerun TCP server using the default address and
 # port: localhost:9876
-rr.connect()
+rr.connect_tcp()
 
 # Log data as usual, thereby pushing it into the TCP socket.
 while True:

diff --git a/docs/snippets/all/concepts/app-model/native-sync.rs b/docs/snippets/all/concepts/app-model/native-sync.rs
@@ -1,7 +1,7 @@
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Connect to the Rerun TCP server using the default address and
     // port: localhost:9876
-    let rec = rerun::RecordingStreamBuilder::new("rerun_example_native_sync").connect()?;
+    let rec = rerun::RecordingStreamBuilder::new("rerun_example_native_sync").connect_tcp()?;
 
     // Log data as usual, thereby pushing it into the TCP socket.
     loop {

diff --git a/docs/snippets/all/quick_start/quick_start_connect.cpp b/docs/snippets/all/quick_start/quick_start_connect.cpp
@@ -6,7 +6,7 @@ using namespace rerun::demo;
 int main() {
     // Create a new `RecordingStream` which sends data over TCP to the viewer process.
     const auto rec = rerun::RecordingStream("rerun_example_quick_start_connect");
-    rec.connect().exit_on_failure();
+    rec.connect_tcp().exit_on_failure();
 
     // Create some data using the `grid` utility function.
     std::vector<rerun::Position3D> points = grid3d<rerun::Position3D, float>(-10.f, 10.f, 10);

diff --git a/docs/snippets/all/quick_start/quick_start_connect.py b/docs/snippets/all/quick_start/quick_start_connect.py
@@ -7,7 +7,7 @@
 rr.init("rerun_example_quick_start_connect")
 
 # Connect to a local viewer using the default port
-rr.connect()
+rr.connect_tcp()
 
 
 # Create some data

diff --git a/docs/snippets/all/quick_start/quick_start_connect.rs b/docs/snippets/all/quick_start/quick_start_connect.rs
@@ -4,7 +4,8 @@ use rerun::{demo_util::grid, external::glam};
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Create a new `RecordingStream` which sends data over TCP to the viewer process.
-    let rec = rerun::RecordingStreamBuilder::new("rerun_example_quick_start_connect").connect()?;
+    let rec =
+        rerun::RecordingStreamBuilder::new("rerun_example_quick_start_connect").connect_tcp()?;
 
     // Create some data using the `grid` utility function.
     let points = grid(glam::Vec3::splat(-10.0), glam::Vec3::splat(10.0), 10);

diff --git a/docs/snippets/all/tutorials/data_out.py b/docs/snippets/all/tutorials/data_out.py
@@ -27,7 +27,7 @@
 
 # Connect to the viewer
 rr.init(recording.application_id(), recording_id=recording.recording_id())
-rr.connect()
+rr.connect_tcp()
 
 # log the jaw open state signal as a scalar
 rr.send_columns(

diff --git a/examples/cpp/log_file/main.cpp b/examples/cpp/log_file/main.cpp
@@ -43,7 +43,7 @@ int main(int argc, char** argv) {
     if (args["spawn"].as<bool>()) {
         rec.spawn().exit_on_failure();
     } else if (args["connect"].as<bool>()) {
-        rec.connect().exit_on_failure();
+        rec.connect_tcp().exit_on_failure();
     } else if (args["stdout"].as<bool>()) {
         rec.to_stdout().exit_on_failure();
     } else if (args.count("save")) {

diff --git a/examples/python/multiprocess_logging/README.md b/examples/python/multiprocess_logging/README.md
@@ -29,7 +29,7 @@ The function `task` is decorated with `@rr.shutdown_at_exit`. This decorator ens
 def task(child_index: int) -> None:
     rr.init("rerun_example_multiprocessing")
 
-    rr.connect()
+    rr.connect_tcp()
 
     title = f"task_{child_index}"
     rr.log(

diff --git a/examples/python/multiprocess_logging/multiprocess_logging.py b/examples/python/multiprocess_logging/multiprocess_logging.py
@@ -24,7 +24,7 @@ def task(child_index: int) -> None:
     rr.init("rerun_example_multiprocessing")
 
     # We then have to connect to the viewer instance.
-    rr.connect()
+    rr.connect_tcp()
 
     title = f"task_{child_index}"
     rr.log(

diff --git a/examples/rust/chess_robby_fischer/README.md b/examples/rust/chess_robby_fischer/README.md
@@ -30,7 +30,7 @@ let app_id = "RobbyFischer";
 let rec_id = uuid::Uuid::new_v4().to_string();
 let rec = rerun::RecordingStreamBuilder::new(app_id)
     .recording_id(&rec_id)
-    .connect()
+    .connect_tcp()
     .unwrap();
 
 // …
@@ -323,7 +323,7 @@ parser.add_argument("--application-id", type=str)
 
 args = parser.parse_args()
 rr.init(args.application_id, recording_id=args.recording_id)
-rr.connect()
+rr.connect_tcp()
 rr.send_blueprint(blueprint)
 ```
 

diff --git a/examples/rust/minimal_serve/src/main.rs b/examples/rust/minimal_serve/src/main.rs
@@ -4,7 +4,7 @@ use rerun::{demo_util::grid, external::glam};
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     let open_browser = true;
-    let rec = rerun::RecordingStreamBuilder::new("rerun_example_minimal_serve").serve(
+    let rec = rerun::RecordingStreamBuilder::new("rerun_example_minimal_serve").serve_web(
         "0.0.0.0",
         Default::default(),
         Default::default(),

diff --git a/rerun_cpp/docs/readme_snippets.cpp b/rerun_cpp/docs/readme_snippets.cpp
@@ -45,7 +45,7 @@ static std::vector<uint8_t> create_image() {
 [[maybe_unused]] static void connecting() {
     /// [Connecting]
     rerun::RecordingStream rec("rerun_example_app");
-    auto result = rec.connect(); // Connect to local host with default port.
+    auto result = rec.connect_tcp(); // Connect to local host with default port.
     if (result.is_err()) {
         // Handle error.
     }

diff --git a/rerun_cpp/src/rerun/recording_stream.cpp b/rerun_cpp/src/rerun/recording_stream.cpp
@@ -101,6 +101,10 @@ namespace rerun {
     }
 
     Error RecordingStream::connect(std::string_view tcp_addr, float flush_timeout_sec) const {
+        return RecordingStream::connect_tcp(tcp_addr, flush_timeout_sec);
+    }
+
+    Error RecordingStream::connect_tcp(std::string_view tcp_addr, float flush_timeout_sec) const {
         rr_error status = {};
         rr_recording_stream_connect(
             _id,