exposed messages and added docs

Author: datomo

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "rusty-tracks"
-version = "0.0.9"
+version = "0.0.10"
 authors = ["David Lengweiler <dave.lengw@gmail.com>"]
 description = "Rust client to connect to DataTracks."
 homepage = "https://github.com/data-tracks/RustyTracks"

Cargo.toml

@@ -1,8 +1,7 @@
 use crate::connection::Connection;
 use crate::messages::{CreatePlan, DeletePlan, Plan, Plans, StartPlan, StopPlan};
-use flatbuffers::FlatBufferBuilder;
+use flatbuffers::{FlatBufferBuilder, WIPOffset};
 use std::ops::{Deref, DerefMut};
-use track_rails::message_generated::protocol;
 use track_rails::message_generated::protocol::{ByName, ByNameArgs, CreatePlanRequest, CreatePlanRequestArgs, DeletePlanRequest, DeletePlanRequestArgs, Filter, FilterArgs, FilterType, GetPlansRequest, GetPlansRequestArgs, Message, MessageArgs, OkStatus, OkStatusArgs, Payload, StartPlanRequest, StartPlanRequestArgs, Status, StopPlanRequest, StopPlanRequestArgs};
 
 pub struct Admin{
@@ -15,79 +14,74 @@ impl Admin {
         Admin{ connection }
     }
 
+    /// Start an already created plan.
     pub fn start_plan(&mut self, id: usize) -> Result<(), String> {
         let mut builder = FlatBufferBuilder::new();
 
         let start = StartPlanRequest::create(&mut builder, &StartPlanRequestArgs{ id: id as u64 });
 
-        let status = OkStatus::create(&mut builder, &OkStatusArgs{});
-
-        let msg = Message::create(&mut builder, &MessageArgs {
-            data_type: Payload::StartPlanRequest,
-            data: Some(start.as_union_value()),
-            status_type: Status::OkStatus,
-            status: Some(status.as_union_value()),
-        });
-
-        builder.finish(msg, None);
-        let msg = builder.finished_data().to_vec();
+        let msg = Self::wrap_msg(&mut builder, Payload::StopPlanRequest, start.as_union_value());
 
         self.write_all(&msg)?;
 
-        let _: StartPlan = self.read_msg()?;
+        let _: StartPlan = self.receive()?;
         Ok(())
     }
 
-    pub(crate) fn stop_plan(&mut self, id: usize) -> Result<(), String> {
+    /// Try to stop a created plan.
+    pub fn stop_plan(&mut self, id: usize) -> Result<(), String> {
         let mut builder = FlatBufferBuilder::new();
 
         let stop = StopPlanRequest::create(&mut builder, &StopPlanRequestArgs{ id: id as u64 });
 
-        let status = OkStatus::create(&mut builder, &OkStatusArgs{});
+        let msg = Self::wrap_msg(&mut builder, Payload::StopPlanRequest, stop.as_union_value());
+
+        self.write_all(&msg)?;
 
-        let msg = Message::create(&mut builder, &MessageArgs {
-            data_type: Payload::StopPlanRequest,
-            data: Some(stop.as_union_value()),
+        let _: StopPlan = self.receive()?;
+        Ok(())
+    }
+
+    fn wrap_msg(builder: &mut FlatBufferBuilder, payload: Payload,data: WIPOffset<flatbuffers::UnionWIPOffset>) -> Vec<u8> {
+        let status = OkStatus::create(builder, &OkStatusArgs{});
+
+        let msg = Message::create(builder, &MessageArgs {
+            data_type: payload,
+            data: Some(data),
             status_type: Status::OkStatus,
             status: Some(status.as_union_value()),
         });
-
         builder.finish(msg, None);
-        let msg = builder.finished_data().to_vec();
-
-        self.write_all(&msg)?;
-
-        let _: StopPlan = self.read_msg()?;
-        Ok(())
+        builder.finished_data().to_vec()
     }
 
+
+    /// Create a new plan with a given name and according to the provided schema.
+    ///
+    /// # Arguments
+    ///
+    /// * `name`: the name of the plan
+    /// * `plan`: the schema of the plan
+    ///
+    /// returns: Result<usize, String>
     pub fn create_plan<Name: AsRef<str>, Plan: AsRef<str>>(&mut self, name: Name, plan: Plan) -> Result<usize, String> {
         let mut builder = FlatBufferBuilder::new();
 
         let name = builder.create_string(name.as_ref());
         let plan = builder.create_string(plan.as_ref());
 
-        let create = CreatePlanRequest::create(&mut builder, &CreatePlanRequestArgs{ name: Some(name), plan: Some(plan) }).as_union_value();
-
-        let status = OkStatus::create(&mut builder, &OkStatusArgs { }).as_union_value();
-
-        let msg = protocol::Message::create(&mut builder, &MessageArgs{
-            data_type: Payload::CreatePlanRequest,
-            data: Some(create),
-            status_type: Status::OkStatus,
-            status: Some(status),
-        });
+        let create = CreatePlanRequest::create(&mut builder, &CreatePlanRequestArgs{ name: Some(name), plan: Some(plan) });
 
-        builder.finish(msg, None);
-        let msg = builder.finished_data();
+        let msg = Self::wrap_msg(&mut builder, Payload::CreatePlanRequest, create.as_union_value());
 
-        self.write_all(msg)?;
+        self.write_all(&msg)?;
 
-        let res: CreatePlan = self.read_msg()?;
+        let res: CreatePlan = self.receive()?;
 
         Ok(res.id)
     }
 
+    /// Get all registered plans, running as well as stopped.
     pub fn get_plans(&mut self) -> Result<Vec<Plan>, String> {
         self.get_plans_by_name("*")
     }
@@ -104,44 +98,30 @@ impl Admin {
         // send request
         let get_plan = GetPlansRequest::create(&mut builder, &GetPlansRequestArgs { name: Some(filter) }).as_union_value();
 
-        let status = OkStatus::create(&mut builder, &OkStatusArgs { }).as_union_value();
-
-        let msg = Message::create(&mut builder, &MessageArgs{
-            data_type: Payload::GetPlansRequest,
-            data: Some(get_plan),
-            status_type: Status::OkStatus,
-            status: Some(status),
-        });
+        let msg = Self::wrap_msg(&mut builder, Payload::GetPlansRequest, get_plan);
 
-        builder.finish(msg, None);
-        let msg = builder.finished_data().to_vec();
         self.write_all(&msg)?;
 
         // wait response
-        let res: Plans = self.read_msg()?;
+        let res: Plans = self.receive()?;
 
         Ok(res.0)
 
     }
 
+    /// Delete a specified plan.
     pub fn delete_plan(&mut self, id: usize) -> Result<(), String> {
         let mut builder = FlatBufferBuilder::new();
 
         // send request
-        let delete = DeletePlanRequest::create(&mut builder, &DeletePlanRequestArgs{ id: id as u64, }).as_union_value();
-        let status = OkStatus::create(&mut builder, &OkStatusArgs { }).as_union_value();
-        let msg = Message::create(&mut builder, &MessageArgs{
-            data_type: Payload::DeletePlanRequest,
-            data: Some(delete),
-            status_type: Status::OkStatus,
-            status: Some(status),
-        });
-        builder.finish(msg, None);
-        let msg = builder.finished_data().to_vec();
+        let delete = DeletePlanRequest::create(&mut builder, &DeletePlanRequestArgs{ id: id as u64, });
+
+        let msg = Self::wrap_msg(&mut builder, Payload::DeletePlanRequest, delete.as_union_value());
+
         self.write_all(&msg)?;
 
         // wait for response
-        let _: DeletePlan = self.read_msg()?;
+        let _: DeletePlan = self.receive()?;
 
         Ok(())
     }

src/connection/admin.rs

@@ -38,12 +38,12 @@ impl Connection {
 
 
     pub fn send<V:Into<Value>>(&mut self, msg: V) -> Result<(), String> {
-        let msg = self.wrap_send(msg.into());
+        let msg = self.wrap(msg.into());
         self.write_all(&msg)
     }
 
-    pub fn receive(&mut self) -> Result<Message, String> {
-        self.read_msg()
+    pub fn receive_msg(&mut self) -> Result<Message, String> {
+        self.receive()
     }
 
     pub fn admin(self) -> Result<Admin, String> {
@@ -82,13 +82,13 @@ impl Connection {
         }
 
 
-        let msg: messages::RegisterResponse = self.read_msg()?;
+        let msg: messages::RegisterResponse = self.receive()?;
         debug!("{:?}", msg);
         self.permissions = msg.permissions;
         Ok(())
     }
 
-    pub fn read_msg<Msg>(&mut self) -> Result<Msg, String> where
+    pub fn receive<Msg>(&mut self) -> Result<Msg, String> where
         Msg: for<'a> TryFrom<protocol::Message<'a>, Error = String> {
         let mut buf = [0u8; 4];
         self.stream.read_exact(&mut buf).map_err(|e| e.to_string())?;
@@ -101,7 +101,7 @@ impl Connection {
         Msg::try_from(msg)
     }
 
-    pub(crate) fn wrap_send(&mut self, msg: Value) -> Vec<u8> {
+    pub(crate) fn wrap(&mut self, msg: Value) -> Vec<u8> {
         let mut builder = FlatBufferBuilder::new();
 
         let millis = SystemTime::now()

src/connection/connection.rs

@@ -6,6 +6,7 @@ mod value;
 pub use connection::Client;
 pub use connection::Connection;
 pub use connection::Permission;
+pub use messages::*;
 
 
 

src/lib.rs

@@ -22,7 +22,7 @@ mod tests{
         let mut connection = client.connect().unwrap();
 
         for _ in 0..10{
-            let value = connection.receive().unwrap();
+            let value = connection.receive_msg().unwrap();
             println!("{:?}", value);
         }
     }
@@ -126,7 +126,7 @@ mod tests{
         let client = Client::new("localhost", output_port);
         let mut connection = client.connect().unwrap();
 
-        println!("{:?}", connection.read_msg::<Train>().unwrap());
+        println!("{:?}", connection.receive::<Train>().unwrap());
 
     }