feat/better docs

jarust/examples/raw_echotest.rs

@@ -1,5 +1,5 @@
-use jarust::jaconfig::ApiInterface;
 use jarust::jaconfig::JaConfig;
+use jarust::jaconfig::JanusAPI;
 use jarust::jaconnection::CreateConnectionParams;
 use jarust::japlugin::AttachHandleParams;
 use jarust::prelude::Attach;
@@ -19,7 +19,7 @@ async fn main() -> anyhow::Result<()> {
         .capacity(capacity)
         .build();
     let mut connection =
-        jarust::connect(config, ApiInterface::WebSocket, RandomTransactionGenerator).await?;
+        jarust::connect(config, JanusAPI::WebSocket, RandomTransactionGenerator).await?;
     let timeout = Duration::from_secs(10);
     let session = connection
         .create_session(CreateConnectionParams {

jarust/examples/restful.rs

@@ -1,5 +1,5 @@
-use jarust::jaconfig::ApiInterface;
 use jarust::jaconfig::JaConfig;
+use jarust::jaconfig::JanusAPI;
 use jarust::jaconnection::CreateConnectionParams;
 use jarust::japlugin::Attach;
 use jarust::japlugin::AttachHandleParams;
@@ -27,7 +27,7 @@ async fn main() -> anyhow::Result<()> {
         .capacity(capacity)
         .build();
     let mut connection =
-        jarust::connect(config, ApiInterface::Restful, RandomTransactionGenerator).await?;
+        jarust::connect(config, JanusAPI::Restful, RandomTransactionGenerator).await?;
     let timeout = Duration::from_secs(10);
 
     let session = connection
@@ -67,6 +67,7 @@ async fn main() -> anyhow::Result<()> {
                     }),
                     EstablishmentProtocol::JSEP(Jsep {
                         sdp: "".to_string(),
+                        trickle: Some(false),
                         jsep_type: JsepType::Offer,
                     }),
                 )

jarust/examples/secure_ws.rs

@@ -1,5 +1,5 @@
-use jarust::jaconfig::ApiInterface;
 use jarust::jaconfig::JaConfig;
+use jarust::jaconfig::JanusAPI;
 use jarust::jaconnection::CreateConnectionParams;
 use jarust::japlugin::Attach;
 use jarust::japlugin::AttachHandleParams;
@@ -27,7 +27,7 @@ async fn main() -> anyhow::Result<()> {
         .capacity(capacity)
         .build();
     let mut connection =
-        jarust::connect(config, ApiInterface::WebSocket, RandomTransactionGenerator).await?;
+        jarust::connect(config, JanusAPI::WebSocket, RandomTransactionGenerator).await?;
     let timeout = Duration::from_secs(10);
 
     let session = connection
@@ -74,6 +74,7 @@ async fn main() -> anyhow::Result<()> {
                     }),
                     EstablishmentProtocol::JSEP(Jsep {
                         sdp: "".to_string(),
+                        trickle: Some(false),
                         jsep_type: JsepType::Offer,
                     }),
                 )

jarust/src/jaconfig.rs

@@ -2,12 +2,12 @@
 pub struct JaConfig {
     pub(crate) url: String,
     pub(crate) apisecret: Option<String>,
-    pub(crate) namespace: String,
+    pub(crate) server_root: String,
     pub(crate) capacity: usize,
 }
 
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
-pub enum ApiInterface {
+pub enum JanusAPI {
     WebSocket,
     Restful,
 }
@@ -17,7 +17,7 @@ impl JaConfig {
         JaConfigBuilder {
             url: NoUrlTypeState,
             apisecret: None,
-            namespace: None,
+            server_root: None,
             capacity: NoCapacityTypeState,
         }
     }
@@ -32,69 +32,79 @@ pub struct WithCapacityTypeState(pub(crate) usize);
 pub struct JaConfigBuilder<U, C> {
     pub(crate) url: U,
     pub(crate) apisecret: Option<String>,
-    pub(crate) namespace: Option<String>,
+    pub(crate) server_root: Option<String>,
     pub(crate) capacity: C,
 }
 
 impl<C> JaConfigBuilder<NoUrlTypeState, C> {
+    /// Set the URL of the Janus server.
     pub fn url(self, url: &str) -> JaConfigBuilder<WithUrlTypeState, C> {
         let Self {
             apisecret,
-            namespace,
+            server_root,
             capacity,
             ..
         } = self;
         JaConfigBuilder {
             apisecret,
-            namespace,
+            server_root,
             capacity,
             url: WithUrlTypeState(url.into()),
         }
     }
 }
 
 impl<U> JaConfigBuilder<U, NoCapacityTypeState> {
+    /// Set the capacity for the Janus client ring buffer
+    ///
+    /// Mandatory for WebSocket and does nothing for Restful
     pub fn capacity(self, cap: usize) -> JaConfigBuilder<U, WithCapacityTypeState> {
         let Self {
             apisecret,
-            namespace,
+            server_root,
             url,
             ..
         } = self;
         JaConfigBuilder {
             apisecret,
-            namespace,
+            server_root,
             url,
             capacity: WithCapacityTypeState(cap),
         }
     }
 }
 
 impl<U, C> JaConfigBuilder<U, C> {
+    /// Set the API secret for the Janus server.
     pub fn apisecret(self, apisecret: &str) -> Self {
         let Self {
-            namespace,
+            server_root,
             url,
             capacity,
             ..
         } = self;
         JaConfigBuilder {
             apisecret: Some(apisecret.into()),
-            namespace,
+            server_root,
             url,
             capacity,
         }
     }
 
-    pub fn namespace(self, namespace: &str) -> Self {
+    /// Set the server root for the Janus server (default "janus")
+    ///
+    /// It's overridable for WebSocket (it's not critical for WebSocket)
+    ///
+    /// It's mandatory for Restful as it should match the server_root in the Janus config file or it will result in 404 errors
+    pub fn server_root(self, server_root: &str) -> Self {
         let Self {
             apisecret,
             url,
             capacity,
             ..
         } = self;
         JaConfigBuilder {
-            namespace: Some(namespace.into()),
+            server_root: Some(server_root.into()),
             apisecret,
             url,
             capacity,
@@ -105,14 +115,14 @@ impl<U, C> JaConfigBuilder<U, C> {
 impl JaConfigBuilder<WithUrlTypeState, WithCapacityTypeState> {
     pub fn build(self) -> JaConfig {
         let Self {
-            namespace,
+            server_root,
             apisecret,
             url,
             capacity,
         } = self;
-        let namespace = namespace.unwrap_or(String::from("janus"));
+        let server_root = server_root.unwrap_or(String::from("janus"));
         JaConfig {
-            namespace,
+            server_root,
             apisecret,
             url: url.0,
             capacity: capacity.0,

jarust/src/jaconnection.rs

@@ -48,7 +48,7 @@ impl JaConnection {
         Ok(session)
     }
 
-    /// Returns janus server info
+    /// Retrieve Janus server info
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all)]
     pub async fn server_info(&mut self, timeout: Duration) -> JaResult<ServerInfoRsp> {
         let res = self.inner.interface.server_info(timeout).await?;

jarust/src/jahandle.rs

@@ -41,16 +41,6 @@ impl JaHandle {
         }
     }
 
-    #[inline]
-    pub fn id(&self) -> u64 {
-        self.inner.id
-    }
-
-    #[inline]
-    pub fn session_id(&self) -> u64 {
-        self.inner.session_id
-    }
-
     /// Send a one-shot message
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all, fields(session_id = self.inner.session_id, handle_id = self.inner.id))]
     pub async fn fire_and_forget(&self, body: Value) -> JaResult<()> {
@@ -86,7 +76,7 @@ impl JaHandle {
         Ok(res)
     }
 
-    /// Send a message and wait for the ack
+    /// Send a message and wait for ackowledgement
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all, fields(session_id = self.inner.session_id, handle_id = self.inner.id))]
     pub async fn send_waiton_ack(&self, body: Value, timeout: Duration) -> JaResult<JaResponse> {
         tracing::debug!("Sending message and waiting for ackowledgement");
@@ -103,7 +93,7 @@ impl JaHandle {
         Ok(ack)
     }
 
-    /// Send a message with a specific establishment protocol and wait for the ack
+    /// Send a message with a specific establishment protocol and wait for ackowledgement
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all, fields(session_id = self.inner.session_id, handle_id = self.inner.id))]
     pub async fn send_waiton_ack_with_est(
         &self,
@@ -148,6 +138,7 @@ impl JaHandle {
 }
 
 impl JaHandle {
+    /// Hang up the associated PeerConnection but keep the handle alive
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all, fields(session_id = self.inner.session_id, handle_id = self.inner.id))]
     pub async fn hangup(&self, timeout: Duration) -> JaResult<()> {
         tracing::info!("Hanging up");
@@ -158,6 +149,7 @@ impl JaHandle {
         Ok(())
     }
 
+    /// Destroy the plugin handle
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all, fields(session_id = self.inner.session_id, handle_id = self.inner.id))]
     pub async fn detach(self, timeout: Duration) -> JaResult<()> {
         tracing::info!("Detaching");
@@ -168,6 +160,7 @@ impl JaHandle {
         Ok(())
     }
 
+    /// Trickles a single ICE candidate to the Janus server
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all, fields(session_id = self.inner.session_id, handle_id = self.inner.id))]
     pub async fn trickle_single_candidate(
         &self,
@@ -183,6 +176,7 @@ impl JaHandle {
         Ok(())
     }
 
+    /// Trickle multiple ICE candidate to the Janus server
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all, fields(session_id = self.inner.session_id, handle_id = self.inner.id))]
     pub async fn trickle_candidates(
         &self,
@@ -198,6 +192,9 @@ impl JaHandle {
         Ok(())
     }
 
+    /// Complete trickle to tell janus server that you sent all the trickle candidates that were gathered.
+    ///
+    /// This should be send after [`trickle_single_candidate`](Self::trickle_single_candidate) or [`trickle_candidates`](Self::trickle_candidates)
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all, fields(session_id = self.inner.session_id, handle_id = self.inner.id))]
     pub async fn complete_trickle(&self, timeout: Duration) -> JaResult<()> {
         tracing::info!("Completing trickle");

jarust/src/jasession.rs

@@ -52,7 +52,7 @@ impl JaSession {
 
         let this = session.clone();
 
-        let keepalive_task = jarust_rt::spawn_with_name("keepalive", async move {
+        let keepalive_task = jarust_rt::spawn("keepalive", async move {
             let _ = this.keep_alive(params.ka_interval).await;
         });
 
@@ -82,6 +82,7 @@ impl JaSession {
 }
 
 impl JaSession {
+    /// Destory the current session
     #[tracing::instrument(level = tracing::Level::DEBUG, skip_all, fields(session_id = self.inner.shared.id))]
     pub async fn destory(&self, timeout: Duration) -> JaResult<()> {
         tracing::info!("Destroying session");
@@ -124,7 +125,6 @@ impl Attach for JaSession {
 }
 
 impl Drop for Exclusive {
-    #[tracing::instrument(parent = None, level = tracing::Level::TRACE, skip(self))]
     fn drop(&mut self) {
         self.tasks.iter().for_each(|task| {
             task.cancel();