From 0d5d15c9d17669b99a66508b799ec80397b4d316 Mon Sep 17 00:00:00 2001 From: Dietmar Maurer Date: Thu, 30 Sep 2021 11:59:21 +0200 Subject: [PATCH] proxmox-rest-server: improve docs And rename enable_file_log to enable_access_log. --- proxmox-rest-server/src/api_config.rs | 56 +++++++++++++++++++++++---- proxmox-rest-server/src/lib.rs | 4 +- proxmox-rest-server/src/rest.rs | 3 +- proxmox-rest-server/src/state.rs | 4 +- src/bin/proxmox-backup-api.rs | 2 +- src/bin/proxmox-backup-proxy.rs | 2 +- 6 files changed, 56 insertions(+), 15 deletions(-) diff --git a/proxmox-rest-server/src/api_config.rs b/proxmox-rest-server/src/api_config.rs index e09f7af9..712c591b 100644 --- a/proxmox-rest-server/src/api_config.rs +++ b/proxmox-rest-server/src/api_config.rs @@ -18,6 +18,7 @@ use crate::{ApiAuth, FileLogger, FileLogOptions, CommandoSocket}; pub type GetIndexFn = fn(Option, Option, &ApiConfig, Parts) -> Response; +/// REST server configuration pub struct ApiConfig { basedir: PathBuf, router: &'static Router, @@ -27,11 +28,25 @@ pub struct ApiConfig { template_files: RwLock>, request_log: Option>>, auth_log: Option>>, - pub api_auth: Arc, + pub(crate) api_auth: Arc, get_index_fn: GetIndexFn, } impl ApiConfig { + /// Creates a new instance + /// + /// `basedir` - File lookups are relative to this directory. + /// + /// `router` - The REST API definition. + /// + /// `env_type` - The environment type. + /// + /// `api_auth` - The Authentification handler + /// + /// `get_index_fn` - callback to generate the root page + /// (index). Please note that this fuctions gets a reference to + /// the [ApiConfig], so it can use [Handlebars] templates + /// ([render_template](Self::render_template) to generate pages. pub fn new>( basedir: B, router: &'static Router, @@ -53,7 +68,7 @@ impl ApiConfig { }) } - pub fn get_index( + pub(crate) fn get_index( &self, auth_id: Option, language: Option, @@ -62,7 +77,7 @@ impl ApiConfig { (self.get_index_fn)(auth_id, language, self, parts) } - pub fn find_method( + pub(crate) fn find_method( &self, components: &[&str], method: Method, @@ -72,7 +87,7 @@ impl ApiConfig { self.router.find_method(components, method, uri_param) } - pub fn find_alias(&self, components: &[&str]) -> PathBuf { + pub(crate) fn find_alias(&self, components: &[&str]) -> PathBuf { let mut prefix = String::new(); let mut filename = self.basedir.clone(); @@ -89,6 +104,18 @@ impl ApiConfig { filename } + /// Register a path alias + /// + /// This can be used to redirect file lookups to a specific + /// directory, e.g.: + /// + /// ``` + /// use proxmox_rest_server::ApiConfig; + /// // let mut config = ApiConfig::new(...); + /// # fn fake(config: &mut ApiConfig) { + /// config.add_alias("extjs", "/usr/share/javascript/extjs"); + /// # } + /// ``` pub fn add_alias(&mut self, alias: S, path: P) where S: Into, P: Into, @@ -96,10 +123,13 @@ impl ApiConfig { self.aliases.insert(alias.into(), path.into()); } - pub fn env_type(&self) -> RpcEnvironmentType { + pub(crate) fn env_type(&self) -> RpcEnvironmentType { self.env_type } + /// Register a [Handlebars] template file + /// + /// Those templates cane be use with [render_template](Self::render_template) to generate pages. pub fn register_template

(&self, name: &str, path: P) -> Result<(), Error> where P: Into @@ -148,7 +178,12 @@ impl ApiConfig { } } - pub fn enable_file_log

( + /// Enable the access log feature + /// + /// When enabled, all requests are logged to the specified file. + /// This function also registers a `api-access-log-reopen` + /// command one the [CommandoSocket]. + pub fn enable_access_log

( &mut self, path: P, dir_opts: Option, @@ -182,6 +217,11 @@ impl ApiConfig { Ok(()) } + /// Enable the authentification log feature + /// + /// When enabled, all authentification requests are logged to the + /// specified file. This function also registers a + /// `api-auth-log-reopen` command one the [CommandoSocket]. pub fn enable_auth_log

( &mut self, path: P, @@ -217,11 +257,11 @@ impl ApiConfig { Ok(()) } - pub fn get_access_log(&self) -> Option<&Arc>> { + pub(crate) fn get_access_log(&self) -> Option<&Arc>> { self.request_log.as_ref() } - pub fn get_auth_log(&self) -> Option<&Arc>> { + pub(crate) fn get_auth_log(&self) -> Option<&Arc>> { self.auth_log.as_ref() } } diff --git a/proxmox-rest-server/src/lib.rs b/proxmox-rest-server/src/lib.rs index 4b8cce96..fc952f2b 100644 --- a/proxmox-rest-server/src/lib.rs +++ b/proxmox-rest-server/src/lib.rs @@ -73,14 +73,14 @@ lazy_static::lazy_static!{ /// Retruns the current process ID (see [libc::getpid]) /// /// The value is cached at startup (so it is invalid after a fork) -pub fn pid() -> i32 { +pub(crate) fn pid() -> i32 { *PID } /// Returns the starttime of the process (see [PidStat]) /// /// The value is cached at startup (so it is invalid after a fork) -pub fn pstart() -> u64 { +pub(crate) fn pstart() -> u64 { *PSTART } diff --git a/proxmox-rest-server/src/rest.rs b/proxmox-rest-server/src/rest.rs index 8c1e34a3..bf4dbb40 100644 --- a/proxmox-rest-server/src/rest.rs +++ b/proxmox-rest-server/src/rest.rs @@ -52,8 +52,9 @@ impl UserInformation for EmptyUserInformation { fn lookup_privs(&self, _userid: &str, _path: &[&str]) -> u64 { 0 } } +/// REST server implementation (configured with [ApiConfig]) pub struct RestServer { - pub api_config: Arc, + api_config: Arc, } const MAX_URI_QUERY_LENGTH: usize = 3072; diff --git a/proxmox-rest-server/src/state.rs b/proxmox-rest-server/src/state.rs index 4585b266..955e3ce3 100644 --- a/proxmox-rest-server/src/state.rs +++ b/proxmox-rest-server/src/state.rs @@ -134,8 +134,8 @@ pub(crate) fn check_last_worker() { } /// Spawns a tokio task that will be tracked for reload -/// and if it is finished, notify the last_worker_listener if we -/// are in shutdown mode +/// and if it is finished, notify the [last_worker_future] if we +/// are in shutdown mode. pub fn spawn_internal_task(task: T) where T: Future + Send + 'static, diff --git a/src/bin/proxmox-backup-api.rs b/src/bin/proxmox-backup-api.rs index 35cfc5f0..275876e5 100644 --- a/src/bin/proxmox-backup-api.rs +++ b/src/bin/proxmox-backup-api.rs @@ -85,7 +85,7 @@ async fn run() -> Result<(), Error> { let dir_opts = CreateOptions::new().owner(backup_user.uid).group(backup_user.gid); let file_opts = CreateOptions::new().owner(backup_user.uid).group(backup_user.gid); - config.enable_file_log( + config.enable_access_log( pbs_buildcfg::API_ACCESS_LOG_FN, Some(dir_opts.clone()), Some(file_opts.clone()), diff --git a/src/bin/proxmox-backup-proxy.rs b/src/bin/proxmox-backup-proxy.rs index a98d4c1f..617fd45a 100644 --- a/src/bin/proxmox-backup-proxy.rs +++ b/src/bin/proxmox-backup-proxy.rs @@ -192,7 +192,7 @@ async fn run() -> Result<(), Error> { let dir_opts = CreateOptions::new().owner(backup_user.uid).group(backup_user.gid); let file_opts = CreateOptions::new().owner(backup_user.uid).group(backup_user.gid); - config.enable_file_log( + config.enable_access_log( pbs_buildcfg::API_ACCESS_LOG_FN, Some(dir_opts.clone()), Some(file_opts.clone()),