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

[Shannon Sterz <s.sterz@proxmox.com>]

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.

docgen: add docgen crate

this crate allows products to easily dump their api definitions to a
`Value` that can be output as json for an api viewer.

meh

Signed-off-by: Shannon Sterz <s.sterz@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



_______________________________________________
pdm-devel mailing list
pdm-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pdm-devel