improve code docs in api2

Note: API methos should be declared pub, so that they show up in the generated docu.
This commit is contained in:
Dietmar Maurer 2021-01-22 15:53:51 +01:00
parent 545706cbee
commit bf78f70885
19 changed files with 96 additions and 52 deletions

View File

@ -1,3 +1,5 @@
//! Access control (Users, Permissions and Authentication)
use anyhow::{bail, format_err, Error};
use serde_json::{json, Value};
@ -177,7 +179,7 @@ fn authenticate_2nd(
/// Create or verify authentication ticket.
///
/// Returns: An authentication ticket with additional infos.
fn create_ticket(
pub fn create_ticket(
username: Userid,
password: String,
path: Option<String>,
@ -253,7 +255,7 @@ fn create_ticket(
///
/// Each user is allowed to change his own password. Superuser
/// can change all passwords.
fn change_password(
pub fn change_password(
userid: Userid,
password: String,
rpcenv: &mut dyn RpcEnvironment,

View File

@ -1,5 +1,6 @@
//! Manage Access Control Lists
use anyhow::{bail, Error};
use ::serde::{Deserialize, Serialize};
use proxmox::api::{api, Router, RpcEnvironment, Permission};
use proxmox::tools::fs::open_file_locked;
@ -9,36 +10,6 @@ use crate::config::acl;
use crate::config::acl::{Role, PRIV_SYS_AUDIT, PRIV_PERMISSIONS_MODIFY};
use crate::config::cached_user_info::CachedUserInfo;
#[api(
properties: {
propagate: {
schema: ACL_PROPAGATE_SCHEMA,
},
path: {
schema: ACL_PATH_SCHEMA,
},
ugid_type: {
schema: ACL_UGID_TYPE_SCHEMA,
},
ugid: {
type: String,
description: "User or Group ID.",
},
roleid: {
type: Role,
}
}
)]
#[derive(Serialize, Deserialize)]
/// ACL list entry.
pub struct AclListItem {
path: String,
ugid: String,
ugid_type: String,
propagate: bool,
roleid: String,
}
fn extract_acl_node_data(
node: &acl::AclTreeNode,
path: &str,

View File

@ -1,3 +1,5 @@
//! List Authentication domains/realms
use anyhow::{Error};
use serde_json::{json, Value};

View File

@ -1,3 +1,5 @@
//! Manage Roles with privileges
use anyhow::Error;
use serde_json::{json, Value};

View File

@ -1,3 +1,5 @@
//! Two Factor Authentication
use anyhow::{bail, format_err, Error};
use serde::{Deserialize, Serialize};

View File

@ -1,3 +1,5 @@
//! User Management
use anyhow::{bail, format_err, Error};
use serde::{Serialize, Deserialize};
use serde_json::{json, Value};

View File

@ -1,3 +1,5 @@
//! Backup Server Administration
use proxmox::api::router::{Router, SubdirMap};
use proxmox::list_subdirs_api_method;

View File

@ -1,3 +1,5 @@
//! Datastore Management
use std::collections::HashSet;
use std::ffi::OsStr;
use std::os::unix::ffi::OsStrExt;
@ -299,7 +301,7 @@ pub fn list_snapshot_files(
},
)]
/// Delete backup snapshot.
fn delete_snapshot(
pub fn delete_snapshot(
store: String,
backup_type: String,
backup_id: String,
@ -795,7 +797,7 @@ pub const API_METHOD_PRUNE: ApiMethod = ApiMethod::new(
true)
);
fn prune(
pub fn prune(
param: Value,
_info: &ApiMethod,
rpcenv: &mut dyn RpcEnvironment,
@ -923,7 +925,7 @@ fn prune(
},
)]
/// Start garbage collection.
fn start_garbage_collection(
pub fn start_garbage_collection(
store: String,
_info: &ApiMethod,
rpcenv: &mut dyn RpcEnvironment,
@ -983,7 +985,7 @@ pub fn garbage_collection_status(
},
)]
/// Datastore list
fn get_datastore_list(
pub fn get_datastore_list(
_param: Value,
_info: &ApiMethod,
rpcenv: &mut dyn RpcEnvironment,
@ -1031,7 +1033,7 @@ pub const API_METHOD_DOWNLOAD_FILE: ApiMethod = ApiMethod::new(
true)
);
fn download_file(
pub fn download_file(
_parts: Parts,
_req_body: Body,
param: Value,
@ -1101,7 +1103,7 @@ pub const API_METHOD_DOWNLOAD_FILE_DECODED: ApiMethod = ApiMethod::new(
true)
);
fn download_file_decoded(
pub fn download_file_decoded(
_parts: Parts,
_req_body: Body,
param: Value,
@ -1215,7 +1217,7 @@ pub const API_METHOD_UPLOAD_BACKUP_LOG: ApiMethod = ApiMethod::new(
&Permission::Privilege(&["datastore", "{store}"], PRIV_DATASTORE_BACKUP, false)
);
fn upload_backup_log(
pub fn upload_backup_log(
_parts: Parts,
req_body: Body,
param: Value,
@ -1294,7 +1296,7 @@ fn upload_backup_log(
},
)]
/// Get the entries of the given path of the catalog
fn catalog(
pub fn catalog(
store: String,
backup_type: String,
backup_id: String,
@ -1462,7 +1464,7 @@ pub const API_METHOD_PXAR_FILE_DOWNLOAD: ApiMethod = ApiMethod::new(
true)
);
fn pxar_file_download(
pub fn pxar_file_download(
_parts: Parts,
_req_body: Body,
param: Value,
@ -1599,7 +1601,7 @@ fn pxar_file_download(
},
)]
/// Read datastore stats
fn get_rrd_stats(
pub fn get_rrd_stats(
store: String,
timeframe: RRDTimeFrameResolution,
cf: RRDMode,
@ -1641,7 +1643,7 @@ fn get_rrd_stats(
},
)]
/// Get "notes" for a specific backup
fn get_notes(
pub fn get_notes(
store: String,
backup_type: String,
backup_id: String,
@ -1691,7 +1693,7 @@ fn get_notes(
},
)]
/// Set "notes" for a specific backup
fn set_notes(
pub fn set_notes(
store: String,
backup_type: String,
backup_id: String,
@ -1736,7 +1738,7 @@ fn set_notes(
},
)]
/// Change owner of a backup group
fn set_backup_owner(
pub fn set_backup_owner(
store: String,
backup_type: String,
backup_id: String,

View File

@ -1,3 +1,5 @@
//! Datastore Syncronization Job Management
use anyhow::{bail, format_err, Error};
use serde_json::Value;
@ -110,7 +112,7 @@ pub fn list_sync_jobs(
},
)]
/// Runs the sync jobs manually.
fn run_sync_job(
pub fn run_sync_job(
id: String,
_info: &ApiMethod,
rpcenv: &mut dyn RpcEnvironment,

View File

@ -1,3 +1,5 @@
//! Datastore Verify Job Management
use anyhow::{format_err, Error};
use proxmox::api::router::SubdirMap;
@ -115,7 +117,7 @@ pub fn list_verification_jobs(
},
)]
/// Runs a verification job manually.
fn run_verification_job(
pub fn run_verification_job(
id: String,
_info: &ApiMethod,
rpcenv: &mut dyn RpcEnvironment,

View File

@ -1,3 +1,5 @@
//! Backup protocol (HTTP2 upgrade)
use anyhow::{bail, format_err, Error};
use futures::*;
use hyper::header::{HeaderValue, UPGRADE};

View File

@ -1,3 +1,5 @@
//! Backup Server Configuration
use proxmox::api::router::{Router, SubdirMap};
use proxmox::list_subdirs_api_method;

View File

@ -1,3 +1,5 @@
//! Server/Node Configuration and Administration
use std::net::TcpListener;
use std::os::unix::io::AsRawFd;

View File

@ -1,3 +1,5 @@
//! Cheap check if the API daemon is online.
use anyhow::{Error};
use serde_json::{json, Value};
@ -20,7 +22,7 @@ use proxmox::api::{api, Router, Permission};
}
)]
/// Dummy method which replies with `{ "pong": True }`
fn ping() -> Result<Value, Error> {
pub fn ping() -> Result<Value, Error> {
Ok(json!({
"pong": true,
}))

View File

@ -1,3 +1,5 @@
//! Backup reader/restore protocol (HTTP2 upgrade)
use anyhow::{bail, format_err, Error};
use futures::*;
use hyper::header::{self, HeaderValue, UPGRADE};

View File

@ -1,3 +1,5 @@
//! Datastote status
use proxmox::list_subdirs_api_method;
use anyhow::{Error};
@ -75,7 +77,7 @@ use crate::config::acl::{
},
)]
/// List Datastore usages and estimates
fn datastore_status(
pub fn datastore_status(
_param: Value,
_info: &ApiMethod,
rpcenv: &mut dyn RpcEnvironment,

View File

@ -1,3 +1,5 @@
//! Tape Backup Management
use proxmox::api::router::SubdirMap;
use proxmox::api::Router;
use proxmox::list_subdirs_api_method;

View File

@ -1,3 +1,5 @@
//! API Type Definitions
use anyhow::bail;
use serde::{Deserialize, Serialize};
@ -5,8 +7,15 @@ use proxmox::api::{api, schema::*};
use proxmox::const_regex;
use proxmox::{IPRE, IPRE_BRACKET, IPV4RE, IPV6RE, IPV4OCTET, IPV6H16, IPV6LS32};
use crate::backup::{CryptMode, Fingerprint, BACKUP_ID_REGEX};
use crate::server::UPID;
use crate::{
backup::{
CryptMode,
Fingerprint,
BACKUP_ID_REGEX,
},
server::UPID,
config::acl::Role,
};
#[macro_use]
mod macros;
@ -282,6 +291,36 @@ pub const ACL_UGID_TYPE_SCHEMA: Schema = StringSchema::new(
EnumEntry::new("group", "Group")]))
.schema();
#[api(
properties: {
propagate: {
schema: ACL_PROPAGATE_SCHEMA,
},
path: {
schema: ACL_PATH_SCHEMA,
},
ugid_type: {
schema: ACL_UGID_TYPE_SCHEMA,
},
ugid: {
type: String,
description: "User or Group ID.",
},
roleid: {
type: Role,
}
}
)]
#[derive(Serialize, Deserialize)]
/// ACL list entry.
pub struct AclListItem {
pub path: String,
pub ugid: String,
pub ugid_type: String,
pub propagate: bool,
pub roleid: String,
}
pub const BACKUP_ARCHIVE_NAME_SCHEMA: Schema =
StringSchema::new("Backup archive name.")
.format(&PROXMOX_SAFE_ID_FORMAT)

View File

@ -1,3 +1,5 @@
//! Version information
use anyhow::{Error};
use serde_json::{json, Value};