From 164c71ddfee36299d0a8c445f7fe41736e71d56c Mon Sep 17 00:00:00 2001 From: JMARyA Date: Wed, 30 Apr 2025 10:02:04 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/api.rs | 13 +++++++++++++ src/herd_core/config.rs | 1 + src/herd_core/model.rs | 7 ++++++- src/herd_core/mqtt.rs | 4 ++++ src/herd_core/route.rs | 1 + src/sheepd_core/cmd.rs | 2 +- src/sheepd_core/config.rs | 6 ++++++ src/sheepd_core/daemon.rs | 3 +++ src/sheepd_core/mqtt.rs | 1 + 9 files changed, 36 insertions(+), 2 deletions(-) diff --git a/src/api.rs b/src/api.rs index 65d567e..32e83f7 100644 --- a/src/api.rs +++ b/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, + /// 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(mut eventloop: EventLoop, handle_payload: F) where F: Fn(String, Vec) -> Fut + Send + Sync + 'static, @@ -77,6 +89,7 @@ where } #[derive(Deserialize, Serialize)] +/// Generic JSON API result pub struct Result { pub ok: u32, } diff --git a/src/herd_core/config.rs b/src/herd_core/config.rs index 2eefab1..1e1094f 100644 --- a/src/herd_core/config.rs +++ b/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 diff --git a/src/herd_core/model.rs b/src/herd_core/model.rs index ceaef09..f4e8cbf 100644 --- a/src/herd_core/model.rs +++ b/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, + /// Identity (Public Keys) + pub identity: (String, String), } impl Machine { diff --git a/src/herd_core/mqtt.rs b/src/herd_core/mqtt.rs index 6decdaa..550bac0 100644 --- a/src/herd_core/mqtt.rs +++ b/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) { 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) { } } +/// Send a message to a registered `machine` pub async fn send_msg(client: &AsyncClient, machine: &Model, request: T) { let data = serde_json::to_string(&request).unwrap(); let pk = &machine.read().identity; @@ -44,6 +46,7 @@ pub async fn send_msg(client: &AsyncClient, machine: &Modelserver` 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> = query!(|_| true); for machine in machines { diff --git a/src/herd_core/route.rs b/src/herd_core/route.rs index 3b82048..b9777d1 100644 --- a/src/herd_core/route.rs +++ b/src/herd_core/route.rs @@ -27,6 +27,7 @@ pub async fn login_user(Json(payload): Json) -> (StatusCode, Json, diff --git a/src/sheepd_core/cmd.rs b/src/sheepd_core/cmd.rs index b57af5e..8b1c7ec 100644 --- a/src/sheepd_core/cmd.rs +++ b/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, diff --git a/src/sheepd_core/config.rs b/src/sheepd_core/config.rs index 4c88897..ad217a9 100644 --- a/src/sheepd_core/config.rs +++ b/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, } diff --git a/src/sheepd_core/daemon.rs b/src/sheepd_core/daemon.rs index b5250c3..2f84c35 100644 --- a/src/sheepd_core/daemon.rs +++ b/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"); diff --git a/src/sheepd_core/mqtt.rs b/src/sheepd_core/mqtt.rs index bbc124b..dea12e6 100644 --- a/src/sheepd_core/mqtt.rs +++ b/src/sheepd_core/mqtt.rs @@ -17,6 +17,7 @@ pub async fn handle_mqtt(topic: String, data: Vec) { ); } +/// Send something back to the server on `topic` pub async fn send_back(client: &AsyncClient, topic: &str, request: T) { let data = serde_json::to_string(&request).unwrap();