From 151c6ce27df285fd96cd50103698d5056465ca74 Mon Sep 17 00:00:00 2001
From: Dietmar Maurer <dietmar@proxmox.com>
Date: Thu, 14 Feb 2019 11:11:39 +0100
Subject: [PATCH] src/client.rs: improve library structure and docu

---
 src/bin/proxmox-backup-client.rs  | 35 +---------------------
 src/client.rs                     | 13 +++++++++
 src/client/backup_repo.rs         | 48 +++++++++++++++++++++++++++++++
 src/client/catar_backup_stream.rs |  7 +++++
 src/client/http_client.rs         |  1 +
 src/lib.rs                        |  6 +---
 6 files changed, 71 insertions(+), 39 deletions(-)
 create mode 100644 src/client.rs
 create mode 100644 src/client/backup_repo.rs

diff --git a/src/bin/proxmox-backup-client.rs b/src/bin/proxmox-backup-client.rs
index 8bbaa0f0..48030dfd 100644
--- a/src/bin/proxmox-backup-client.rs
+++ b/src/bin/proxmox-backup-client.rs
@@ -7,8 +7,7 @@ use proxmox_backup::tools;
 use proxmox_backup::cli::command::*;
 use proxmox_backup::api::schema::*;
 use proxmox_backup::api::router::*;
-use proxmox_backup::client::http_client::*;
-use proxmox_backup::client::catar_backup_stream::*;
+use proxmox_backup::client::*;
 //use proxmox_backup::backup::chunk_store::*;
 //use proxmox_backup::backup::image_index::*;
 //use proxmox_backup::config::datastore;
@@ -18,38 +17,6 @@ use proxmox_backup::client::catar_backup_stream::*;
 use serde_json::{Value};
 use hyper::Body;
 use std::sync::Arc;
-use lazy_static::lazy_static;
-use regex::Regex;
-
-lazy_static! {
-    // user@host:datastore
-    pub static ref BACKUP_REPO_URL_REGEX: Regex = Regex::new(r"^(?:(?:([\w@]+)@)?(\w+):)?(\w+)$").unwrap();
-
-    pub static ref BACKUP_REPO_URL: Arc<ApiStringFormat> =
-        ApiStringFormat::Pattern(&BACKUP_REPO_URL_REGEX).into();
-}
-
-#[derive(Debug)]
-pub struct BackupRepository {
-    pub user: String,
-    pub host: String,
-    pub store: String,
-}
-
-impl BackupRepository {
-
-    pub fn parse(url: &str) -> Result<Self, Error> {
-
-        let cap = BACKUP_REPO_URL_REGEX.captures(url)
-            .ok_or_else(|| format_err!("unable to parse reepository url '{}'", url))?;
-
-        Ok(BackupRepository {
-            user: cap.get(1).map_or("root@pam", |m| m.as_str()).to_owned(),
-            host: cap.get(2).map_or("localhost", |m| m.as_str()).to_owned(),
-            store: cap[3].to_owned(),
-        })
-    }
-}
 
 fn backup_directory(repo: &BackupRepository, body: Body, archive_name: &str) -> Result<(), Error> {
 
diff --git a/src/client.rs b/src/client.rs
new file mode 100644
index 00000000..5eb7e05a
--- /dev/null
+++ b/src/client.rs
@@ -0,0 +1,13 @@
+//! Client side interface to the proxmox backup server
+//!
+//! This library implements the client side to access the backups
+//! server using https.
+
+mod http_client;
+pub use  http_client::*;
+
+mod catar_backup_stream;
+pub use catar_backup_stream::*;
+
+mod backup_repo;
+pub use backup_repo::*;
diff --git a/src/client/backup_repo.rs b/src/client/backup_repo.rs
new file mode 100644
index 00000000..0d88f0e5
--- /dev/null
+++ b/src/client/backup_repo.rs
@@ -0,0 +1,48 @@
+use failure::*;
+
+use crate::api::schema::*;
+
+use std::sync::Arc;
+use lazy_static::lazy_static;
+use regex::Regex;
+
+lazy_static! {
+    // user@host:datastore
+    pub static ref BACKUP_REPO_URL_REGEX: Regex = Regex::new(r"^(?:(?:([\w@]+)@)?(\w+):)?(\w+)$").unwrap();
+
+    pub static ref BACKUP_REPO_URL: Arc<ApiStringFormat> =
+        ApiStringFormat::Pattern(&BACKUP_REPO_URL_REGEX).into();
+}
+
+/// Reference remote backup locations
+///
+
+#[derive(Debug)]
+pub struct BackupRepository {
+    /// The user name used for Authentication
+    pub user: String,
+    /// The host name or IP address
+    pub host: String,
+    /// The name of the datastore
+    pub store: String,
+}
+
+impl BackupRepository {
+
+    /// Parse a repository string.
+    ///
+    /// This parses strings like `user@host:datastore`. The `user` and
+    /// `host` parts are optional, where `host` defaults to the local
+    /// host, and `user` defaults to `root@pam`.
+    pub fn parse(url: &str) -> Result<Self, Error> {
+
+        let cap = BACKUP_REPO_URL_REGEX.captures(url)
+            .ok_or_else(|| format_err!("unable to parse reepository url '{}'", url))?;
+
+        Ok(BackupRepository {
+            user: cap.get(1).map_or("root@pam", |m| m.as_str()).to_owned(),
+            host: cap.get(2).map_or("localhost", |m| m.as_str()).to_owned(),
+            store: cap[3].to_owned(),
+        })
+    }
+}
diff --git a/src/client/catar_backup_stream.rs b/src/client/catar_backup_stream.rs
index de27f1d7..ebb8a126 100644
--- a/src/client/catar_backup_stream.rs
+++ b/src/client/catar_backup_stream.rs
@@ -13,6 +13,13 @@ use nix::dir::Dir;
 
 use crate::catar::encoder::*;
 
+/// Stream implementation to encode and upload .catar archives.
+///
+/// The hyper client needs an async Stream for file upload, so we
+/// spawn an extra thread to encode the .catar data and pipe it to the
+/// consumer.
+///
+/// Note: The currect implementation is not fully ansync and can block.
 pub struct CaTarBackupStream {
     pipe: Option<std::fs::File>,
     buffer: Vec<u8>,
diff --git a/src/client/http_client.rs b/src/client/http_client.rs
index 3b76b454..c53032c8 100644
--- a/src/client/http_client.rs
+++ b/src/client/http_client.rs
@@ -11,6 +11,7 @@ use futures::stream::Stream;
 use serde_json::{Value};
 use url::percent_encoding::{percent_encode,  DEFAULT_ENCODE_SET};
 
+/// HTTP(S) API client
 pub struct HttpClient {
     username: String,
     server: String,
diff --git a/src/lib.rs b/src/lib.rs
index 21048399..f49930d3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -61,11 +61,7 @@ pub mod cli {
 
 pub mod api2;
 
-pub mod client {
-
-    pub mod http_client;
-    pub mod catar_backup_stream;
-}
+pub mod client;
 
 pub mod getopts;
 pub mod auth_helpers;