📝 docs

src/api.rs

@@ -4,20 +4,31 @@ use std::time::Duration;
 use tokio::time::sleep;
 
 #[derive(Deserialize, Serialize)]
+/// Join Request
 pub struct JoinParams {
+    /// Optional join token
     pub join_token: Option<String>,
+    /// Machine ID
     pub machine_id: String,
+    /// Hostname
     pub hostname: String,
+    /// Public Key Identity
     pub identity: (String, String),
 }
 
 #[derive(Deserialize, Serialize)]
 pub struct JoinResponse {
+    /// Server Token
     pub token: String,
+    /// Server Identity
     pub identity: (String, String),
+    /// MQTT endpoint
     pub mqtt: String,
 }
 
+/// Setup a MQTT connection for `machine_id` on `mqtt`.
+///
+/// This will connect either over `ws://` or `wss://` depending on the scheme of `mqtt`. By default it will use `wss://`.
 pub fn mqtt_connect(machine_id: &str, mqtt: &str) -> (rumqttc::AsyncClient, rumqttc::EventLoop) {
     let mqttoptions = if mqtt.starts_with("ws://") {
         log::warn!("Using unencrypted WebSocket connection");
@@ -46,6 +57,7 @@ pub fn mqtt_connect(machine_id: &str, mqtt: &str) -> (rumqttc::AsyncClient, rumq
     AsyncClient::new(mqttoptions, 10)
 }
 
+/// Run the async MQTT event loop
 pub async fn run_event_loop<F, Fut>(mut eventloop: EventLoop, handle_payload: F)
 where
     F: Fn(String, Vec<u8>) -> Fut + Send + Sync + 'static,
@@ -77,6 +89,7 @@ where
 }
 
 #[derive(Deserialize, Serialize)]
+/// Generic JSON API result
 pub struct Result {
     pub ok: u32,
 }

src/herd_core/config.rs

@@ -1,5 +1,6 @@
 use serde::{Deserialize, Serialize};
 
+/// Herd Server Configuration
 #[derive(Serialize, Deserialize)]
 pub struct Config {
     /// Public MQTT endpoint

src/herd_core/model.rs

@@ -2,13 +2,18 @@ use crate::api;
 use crate::generate_token;
 use owl::prelude::*;
 
+/// Joined Machine
 #[model]
 pub struct Machine {
+    /// Machine ID
     pub id: Id,
+    /// Hostname
     pub hostname: String,
+    /// Token
     pub token: String,
-    pub identity: (String, String),
     pub next_token: Option<String>,
+    /// Identity (Public Keys)
+    pub identity: (String, String),
 }
 
 impl Machine {

src/herd_core/mqtt.rs

@@ -4,6 +4,7 @@ use owl::{Serialize, get, query};
 use rumqttc::AsyncClient;
 use sage::PersonaIdentity;
 
+/// Handle herd MQTT
 pub async fn handle_mqtt(topic: String, data: Vec<u8>) {
     log::info!("Received client request from {topic}");
     let (client, cat) = topic.split_once('/').unwrap();
@@ -26,6 +27,7 @@ pub async fn handle_mqtt(topic: String, data: Vec<u8>) {
     }
 }
 
+/// Send a message to a registered `machine`
 pub async fn send_msg<T: Serialize>(client: &AsyncClient, machine: &Model<Machine>, request: T) {
     let data = serde_json::to_string(&request).unwrap();
     let pk = &machine.read().identity;
@@ -44,6 +46,7 @@ pub async fn send_msg<T: Serialize>(client: &AsyncClient, machine: &Model<Machin
         .unwrap();
 }
 
+/// Subscribe to all `device->server` topics
 pub async fn listen_to_device(client: &AsyncClient, machine_id: &str) {
     // Online Presence
     client
@@ -52,6 +55,7 @@ pub async fn listen_to_device(client: &AsyncClient, machine_id: &str) {
         .unwrap();
 }
 
+/// Subscibe to incoming messages from all registered machines
 pub async fn listen_to_devices(client: &AsyncClient) {
     let machines: Vec<Model<Machine>> = query!(|_| true);
     for machine in machines {

src/herd_core/route.rs

@@ -27,6 +27,7 @@ pub async fn login_user(Json(payload): Json<LoginParam>) -> (StatusCode, Json<se
     }
 }
 
+/// Route for joining devices (`/join`)
 pub async fn join_device(
     ClientIp(ip): ClientIp,
     Json(payload): Json<api::JoinParams>,

src/sheepd_core/cmd.rs

@@ -17,6 +17,7 @@ fn domain(host: &str) -> String {
     }
 }
 
+/// Join a herd as client
 pub fn join(conf: JoinCommand) {
     // TODO : check for root
     // TODO : check if joined somewhere already
@@ -34,7 +35,6 @@ pub fn join(conf: JoinCommand) {
     };
 
     let url = format!("{}/join", domain(&conf.home));
-    println!("{url}");
     let mut res = ureq::post(url)
         .send_json(&api::JoinParams {
             join_token: None,

src/sheepd_core/config.rs

@@ -2,12 +2,18 @@ use owl::{Deserialize, Serialize};
 
 use crate::api::JoinResponse;
 
+/// Client agent configuration at `/etc/sheepd/config.toml`
 #[derive(Serialize, Deserialize, Debug)]
 pub struct AgentConfig {
+    /// Homeserver Domain
     pub home: String,
+    /// Homeserver Token
     pub token: String,
+    /// MQTT endpoint
     pub mqtt: String,
+    /// Server Public Encryption Key
     pub server_age: String,
+    /// Server Public Sign Key
     pub server_sign: String,
 }
 

src/sheepd_core/daemon.rs

@@ -8,6 +8,8 @@ use crate::{api, sheepd_core::config::AgentConfig};
 
 use super::mqtt::send_back;
 
+/// Report online status back to the server.
+/// By default every 60 seconds.
 pub async fn report_online(client: AsyncClient) {
     loop {
         send_back(&client, "online", json!(crate::api::Result::Ok())).await;
@@ -15,6 +17,7 @@ pub async fn report_online(client: AsyncClient) {
     }
 }
 
+/// Start the daemon loop
 pub async fn start_daemon() {
     log::info!("Starting sheepd");
 

src/sheepd_core/mqtt.rs

@@ -17,6 +17,7 @@ pub async fn handle_mqtt(topic: String, data: Vec<u8>) {
     );
 }
 
+/// Send something back to the server on `topic`
 pub async fn send_back<T: Serialize>(client: &AsyncClient, topic: &str, request: T) {
     let data = serde_json::to_string(&request).unwrap();