feat: add live frontend API

.github/workflows/checks.yml

@@ -33,6 +33,9 @@ jobs:
          - name: 🔨 Build
            run: cargo build --verbose
 
+         - name: 🪶 Build actor-only libtortillas
+           run: cargo check -p libtortillas --no-default-features
+
          - name: Install latest nextest release
            uses: taiki-e/install-action@nextest
 

README.md

@@ -20,7 +20,7 @@ See our roadmap [here](https://github.com/users/artrixdotdev/projects/6).
 
 
 ### 📈 Future Plans
-- Frontend TUI (Text User Interface)
+- TUI (Text User Interface)
 
 ### ❌ Not Planned
 - WebTorrent connections: Due to the lack of clear documentation and complex, undocumented protocols WebTorrent support is not currently planned.
@@ -70,7 +70,7 @@ Keep tests focused on one behavior, prefer deterministic fixtures with `include_
 
 ## 📦 Installation
 ### Tortillas
-Tortillas is the frontend TUI (Text User Interface) application (what most people want)
+Tortillas is the TUI (Text User Interface) application most people will use.
 
 There are plans to publish tortillas to registries such as [crates.io](https://crates.io) and [the AUR](https://aur.archlinux.org). However, for now, you can install it from source using cargo:
 ```bash
@@ -81,12 +81,23 @@ This will install `tortillas` to your local Rust toolchain.
 
 
 ### Libtortillas
-Libtortillas is the library that powers the frontend TUI application. It is a library that can be used to build your own frontend application or integrate with existing frontend applications.
+Libtortillas is the engine behind the TUI. It can also be embedded in other
+applications that need BitTorrent downloads, seeding, and observable progress.
 
 ```bash
 cargo add --git https://github.com/artrixdotdev/tortillas libtortillas
 ```
 
+The `live` feature is enabled by default and provides views, metrics, event
+streams, and listener handles. Applications that only need actor-backed
+commands and direct state queries can remove that projection and publication
+overhead:
+
+```toml
+[dependencies]
+libtortillas = { git = "https://github.com/artrixdotdev/tortillas", default-features = false }
+```
+
 #### Runtime Contract
 
 `libtortillas` is a Tokio-first library. Applications that use it must run
@@ -96,11 +107,17 @@ For the Tortillas TUI, the binary should own a single application runtime,
 typically through `#[tokio::main]`, and create `libtortillas::engine::Engine`
 inside that runtime. UI rendering or terminal input that blocks should run on a
 dedicated thread or, for bounded work, through Tokio blocking tasks, then send
-commands into async engine tasks. Long-lived input loops should use a dedicated
+application actions into async engine tasks. Long-lived input loops should use a dedicated
 thread because `spawn_blocking` tasks cannot be aborted once they start. The
 library does not currently support swapping in a different async runtime, HTTP
 client, clock, listener, or storage executor.
 
+With the default `live` feature, use listeners for current state and
+incremental updates, and call `Engine` and `Torrent` methods for operations. Do
+not poll persistence snapshots to drive a display. See the
+[`libtortillas::live` API documentation](https://docs.rs/libtortillas/latest/libtortillas/live/) and the
+[`live` example](crates/libtortillas/examples/live.rs).
+
 ## 🤝 Contributing
 
 We welcome contributions! If you'd like to help improve `tortillas`, please check out our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and tips.

crates/libtortillas/Cargo.toml

@@ -9,6 +9,9 @@ keywords = ["bittorrent", "p2p", "torrent"]
 categories = ["network-programming", "concurrency"]
 readme = "../../README.md"
 
+[features]
+default = ["live"]
+live = ["dep:tokio-stream"]
 
 [dependencies]
 serde = { workspace = true }
@@ -39,8 +42,29 @@ kameo_actors = "^0.5"
 dashmap = { version = "^6", features = ["serde"] }
 bon = "^3.9"
 tokio-util = "^0.7"
+tokio-stream = { version = "^0.1", features = ["sync"], optional = true }
 
 [dev-dependencies]
 tracing-test = "0.2.6"
 tracing-subscriber = { workspace = true }
 serde_json = "^1"
+
+[[example]]
+name = "live"
+required-features = ["live"]
+
+[[test]]
+name = "dht_network"
+required-features = ["live"]
+
+[[test]]
+name = "engine_lifecycle"
+required-features = ["live"]
+
+[[test]]
+name = "live"
+required-features = ["live"]
+
+[[test]]
+name = "persistence"
+required-features = ["live"]

crates/libtortillas/examples/live.rs

@@ -0,0 +1,85 @@
+use std::path::PathBuf;
+
+use libtortillas::prelude::{
+   Engine, EngineEventKind, EventStreamError, TorrentEventKind, TorrentSource, TorrentState,
+};
+use tracing::{error, info, warn};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+   tracing_subscriber::fmt()
+      .with_env_filter("live=trace,off")
+      .init();
+   let mut args = std::env::args_os().skip(1).map(PathBuf::from);
+   let Some(torrent_path) = args.next() else {
+      error!("pass a .torrent file path and optional session path to run the example");
+      return Ok(());
+   };
+
+   println!("Torrent path: {:?}", torrent_path);
+   let session_path = args.next();
+
+   let engine = Engine::default();
+   let mut listener = engine.listener();
+   let event_task = tokio::spawn(async move {
+      loop {
+         match listener.recv().await {
+            Ok(event) => {
+               let view = listener.view();
+               info!(
+                  sequence = event.sequence,
+                  torrent_count = view.torrent_count(),
+                  ?event.kind,
+                  "received an engine event"
+               );
+               if matches!(event.kind, EngineEventKind::Shutdown(_)) {
+                  break;
+               }
+            }
+            Err(EventStreamError::Lagged(events)) => {
+               let view = listener.view();
+               warn!(
+                  events,
+                  torrent_count = view.torrent_count(),
+                  "refreshing current state after lag"
+               );
+            }
+            Err(EventStreamError::Closed) => {
+               info!("engine event stream closed");
+               break;
+            }
+         }
+      }
+   });
+
+   let torrent = engine
+      .add_torrent(TorrentSource::torrent_file_path(torrent_path))
+      .await?;
+
+   let mut torrent_listener = torrent.listener();
+   torrent.pause().await?;
+   let paused = loop {
+      let event = torrent_listener.recv().await?;
+      if matches!(
+         event.kind,
+         TorrentEventKind::StateChanged {
+            current: TorrentState::Paused,
+            ..
+         }
+      ) {
+         break event;
+      }
+   };
+   info!(sequence = paused.sequence, ?paused.kind, "torrent paused");
+   torrent.start().await?;
+
+   tokio::signal::ctrl_c().await?;
+   if let Some(path) = session_path {
+      let snapshot = engine.snapshot().await?;
+      tokio::fs::write(&path, serde_json::to_vec_pretty(&snapshot)?).await?;
+      info!(?path, "saved resumable engine state");
+   }
+   engine.shutdown().await?;
+   event_task.await?;
+   Ok(())
+}