From 8b46aac3585d5ce413d0efaf84e8e34471ad87a4 Mon Sep 17 00:00:00 2001
From: Maxim Vorobjov <maxim.vorobjov@gmail.com>
Date: Fri, 1 Nov 2019 23:30:52 +0300
Subject: [PATCH] Allow to extend agent communication from external crates
 (#721)

* allow to extend agent communication from external crates

* Fixing build on rustc 1.35

* implement Default for AgentScope with public new

* toml-rs 0.5.5 fixed compatibility with rustc 1.35
---
 src/agent.rs | 49 ++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 38 insertions(+), 11 deletions(-)

diff --git a/src/agent.rs b/src/agent.rs
index 421b93b7858..4c3285828df 100644
--- a/src/agent.rs
+++ b/src/agent.rs
@@ -18,23 +18,33 @@ use stdweb::Value;
 #[allow(unused_imports)]
 use stdweb::{_js_impl, js};
 
-#[derive(Serialize, Deserialize)]
-enum ToWorker<T> {
+/// Serializable messages to worker
+#[derive(Serialize, Deserialize, Debug)]
+pub enum ToWorker<T> {
+    /// Client is connected
     Connected(HandlerId),
+    /// Incoming message to Worker
     ProcessInput(HandlerId, T),
+    /// Client is disconnected
     Disconnected(HandlerId),
+    /// Worker should be terminated
     Destroy,
 }
 
-#[derive(Serialize, Deserialize)]
-enum FromWorker<T> {
+/// Serializable messages sent by worker to consumer
+#[derive(Serialize, Deserialize, Debug)]
+pub enum FromWorker<T> {
     /// Worker sends this message when `wasm` bundle has loaded.
     WorkerLoaded,
+    /// Outgoing message to consumer
     ProcessOutput(HandlerId, T),
 }
 
-trait Packed {
+/// Message packager, based on serde::Serialize/Deserialize
+pub trait Packed {
+    /// Pack serializable message into Vec<u8>
     fn pack(&self) -> Vec<u8>;
+    /// Unpack deserializable message of byte slice
     fn unpack(data: &[u8]) -> Self;
 }
 
@@ -713,12 +723,13 @@ impl<AGN: Agent> Clone for AgentScope<AGN> {
 }
 
 impl<AGN: Agent> AgentScope<AGN> {
-    fn new() -> Self {
+    /// Create agent scope
+    pub fn new() -> Self {
         let shared_agent = Rc::new(RefCell::new(AgentRunnable::new()));
         AgentScope { shared_agent }
     }
-
-    fn send(&self, update: AgentUpdate<AGN>) {
+    /// Schedule message for sending to agent
+    pub fn send(&self, update: AgentUpdate<AGN>) {
         let envelope = AgentEnvelope {
             shared_agent: self.shared_agent.clone(),
             update,
@@ -728,7 +739,15 @@ impl<AGN: Agent> AgentScope<AGN> {
     }
 }
 
-trait Responder<AGN: Agent> {
+impl<AGN: Agent> Default for AgentScope<AGN> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Defines communication from Worker to Consumers
+pub trait Responder<AGN: Agent> {
+    /// Implementation for communication channel from Worker to Consumers
     fn response(&self, id: HandlerId, output: AGN::Output);
 }
 
@@ -753,7 +772,7 @@ pub struct AgentLink<AGN: Agent> {
 
 impl<AGN: Agent> AgentLink<AGN> {
     /// Create link for a scope.
-    fn connect<T>(scope: &AgentScope<AGN>, responder: T) -> Self
+    pub fn connect<T>(scope: &AgentScope<AGN>, responder: T) -> Self
     where
         T: Responder<AGN> + 'static,
     {
@@ -804,12 +823,20 @@ impl<AGN> AgentRunnable<AGN> {
     }
 }
 
-enum AgentUpdate<AGN: Agent> {
+/// Local Agent messages
+#[derive(Debug)]
+pub enum AgentUpdate<AGN: Agent> {
+    /// Request to create link
     Create(AgentLink<AGN>),
+    /// Internal Agent message
     Message(AGN::Message),
+    /// Client connected
     Connected(HandlerId),
+    /// Received mesasge from Client
     Input(AGN::Input, HandlerId),
+    /// Client disconnected
     Disconnected(HandlerId),
+    /// Request to destroy agent
     Destroy,
 }