From 966648ac8ab087c05166cc52f84d7b08a5236df4 Mon Sep 17 00:00:00 2001 From: Richard Petrie Date: Mon, 16 Apr 2018 11:46:32 -0500 Subject: [PATCH] Initial lib documentation. Touches #15. --- inquisitor_lib/src/lib.rs | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/inquisitor_lib/src/lib.rs b/inquisitor_lib/src/lib.rs index f522a75..650a3af 100644 --- a/inquisitor_lib/src/lib.rs +++ b/inquisitor_lib/src/lib.rs @@ -1,3 +1,6 @@ +//! This library is intended for use in both the Inquisitor Agent and the Inquisitor Receptor. +//! Plugin authors must implement the plugin trait for their desired platform, but they +//! may also make use of several convience functions included in this library. #[macro_use] extern crate serde_derive; extern crate serde; @@ -19,7 +22,8 @@ use std::collections::HashMap; use std::path::PathBuf; use std::time::{SystemTime, UNIX_EPOCH}; - +/// This struct is for communication between agent and receptor. +/// Plugins should not use this directly #[derive(Serialize, Deserialize, Debug)] pub struct Status { pub sender: String, @@ -28,6 +32,7 @@ pub struct Status { pub plugin_name: String } +/// A utility function that returns the current timestamp in seconds pub fn current_ts() -> i64 { SystemTime::now() .duration_since(UNIX_EPOCH) @@ -35,6 +40,10 @@ pub fn current_ts() -> i64 { .as_secs() as i64 } +/// A utility function that returns a deserialized object from a configuration file. +/// Plugins should use this instead of manipulating their own configuration file +/// +/// # TODO examples pub fn read_cfg(cfg_file_path: &PathBuf) -> Result where ConfigT: DeserializeOwned @@ -45,11 +54,15 @@ where Ok(cfg) } +/// This trait is required by agent plugins pub trait AgentPlugin { + /// Returns the plugin's name. Sent to the server to tag plugin messages fn name(&self) -> &'static str; - + /// This is the 'worker' function, and will be called when the ready fucntion returns true. + /// Currently this requires plugins to return a string. + /// An `Ok` will be sent to the server, while currently an `Err` is output to the terminal on the agent fn gather(&mut self) -> Result; - + /// This function tells the agent if the plugin is ready to be run. fn ready(&self) -> bool; } @@ -61,10 +74,14 @@ pub fn get_url_params(req: &Request) -> HashMap { hash_query } +/// This trait is required by receptor plugins pub trait ReceptorPlugin { + /// Returns the plugin's name. Stored in the database with the message returnd fn name(&self) -> &'static str; - + /// This is the 'worker' function, and will be called when the ready fucntion returns true. + /// Currently this requires plugins to return a string. + /// An `Ok` will be stored, while currently an `Err` is output to the terminal on the receptor fn gather(&mut self, db_conn: &Connection) -> Result; - + /// This function tells the receptor if the plugin is ready to be run. fn ready(&self) -> bool; }