[pdm-devel] [PATCH proxmox v4 1/5] router/api-macro: add unstable flag for ApiMethod

[Shannon Sterz]

this allows marking certain api endpoints as unstable. an unstable api
endpoint gives no guarantees that it will stay compatible between
different versions. programmers that make use of an unstable endpoint,
have to expect that anything is subject to change.

Signed-off-by: Shannon Sterz <s.sterz at proxmox.com>
Tested-by: Lukas Wagner <l.wagner at proxmox.com>
Reviewed-by: Lukas Wagner <l.wagner at proxmox.com>
---
 proxmox-api-macro/src/api/method.rs |  9 ++++++++-
 proxmox-router/src/router.rs        | 10 ++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/proxmox-api-macro/src/api/method.rs b/proxmox-api-macro/src/api/method.rs
index d3d17447..68969735 100644
--- a/proxmox-api-macro/src/api/method.rs
+++ b/proxmox-api-macro/src/api/method.rs
@@ -245,6 +245,12 @@ pub fn handle_method(mut attribs: JSONObject, func: syn::ItemFn) -> Result<Token
         .transpose()?
         .unwrap_or(false);

+    let unstable: bool = attribs
+        .remove("unstable")
+        .map(TryFrom::try_from)
+        .transpose()?
+        .unwrap_or(false);
+
     if !attribs.is_empty() {
         error!(
             attribs.span(),
@@ -329,7 +335,8 @@ pub fn handle_method(mut attribs: JSONObject, func: syn::ItemFn) -> Result<Token
             #returns_schema_setter
             #access_setter
             .reload_timezone(#reload_timezone)
-            .protected(#protected);
+            .protected(#protected)
+            .unstable(#unstable);

         #default_consts

diff --git a/proxmox-router/src/router.rs b/proxmox-router/src/router.rs
index 732ced8b..f4207d2a 100644
--- a/proxmox-router/src/router.rs
+++ b/proxmox-router/src/router.rs
@@ -789,6 +789,8 @@ pub struct ApiMethod {
     /// The protected flag indicates that the provides function should be forwarded
     /// to the daemon running in privileged mode.
     pub protected: bool,
+    /// Whether this method is still experimental or already stable.
+    pub unstable: bool,
     /// This flag indicates that the provided method may change the local timezone, so the server
     /// should do a tzset afterwards
     pub reload_timezone: bool,
@@ -820,6 +822,7 @@ impl ApiMethod {
             handler,
             returns: ReturnType::new(false, &NULL_SCHEMA),
             protected: false,
+            unstable: false,
             reload_timezone: false,
             access: ApiAccess {
                 description: None,
@@ -838,6 +841,7 @@ impl ApiMethod {
             handler: &DUMMY_HANDLER,
             returns: ReturnType::new(false, &NULL_SCHEMA),
             protected: false,
+            unstable: false,
             reload_timezone: false,
             access: ApiAccess {
                 description: None,
@@ -858,6 +862,12 @@ impl ApiMethod {
         self
     }

+    pub const fn unstable(mut self, unstable: bool) -> Self {
+        self.unstable = unstable;
+
+        self
+    }
+
     pub const fn reload_timezone(mut self, reload_timezone: bool) -> Self {
         self.reload_timezone = reload_timezone;

--
2.47.3