Group experimental feature flags and expose them via /version

Summary:
Move the scattered `experimental_enable_*` config fields on
`CommonOptions` into a dedicated `Experimental` struct, generated by an
`experimental!` macro from a single list of feature names, and expose
their enabled/disabled state through the admin `/version` endpoint.

Adding a new flag is now a one-line change: declare the identifier in
the `experimental! { ... }` block and the macro emits the config field,
`is_<name>_enabled()` / `set_<name>()` accessors, and the `/version`
entry. Naming is split between the two surfaces:

- the on-disk config / JSON schema keeps the explicit
  `experimental_enable_<name>` field, so existing configurations and
  the schema are unchanged;
- `/version` reports the bare feature name (no `experimental_enable_`
  prefix) to keep the API output compact.

Example `/version` response:
```
    {
      "version": "1.7.0-dev",
      "min_admin_api_version": 2,
      "max_admin_api_version": 4,
      "ingress_endpoint": "http://127.0.0.1:8080/",
      "features": {
        "vqueues": false,
        "protocol_v7": true,
        "invoker_yield": false
      }
    }
```

Note: the reason this is done this way is because serde does not
allow dyanmic field renames

Author: muhamadazmy

crates/admin-rest-model/src/version.rs

@@ -8,7 +8,7 @@
 // the Business Source License, use of this software will be governed
 // by the Apache License, Version 2.0.
 
-use std::ops::RangeInclusive;
+use std::{borrow::Cow, collections::HashMap, ops::RangeInclusive};
 
 use serde::{Deserialize, Serialize};
 
@@ -75,6 +75,12 @@ pub struct VersionInformation {
     ///
     /// Ingress endpoint that the Web UI should use to interact with.
     pub ingress_endpoint: Option<AdvertisedAddress<HttpIngressPort>>,
+
+    /// # Restate experimental features
+    ///
+    /// List experimental features with their
+    /// enabled state.
+    pub features: HashMap<Cow<'static, str>, bool>,
 }
 
 #[cfg(test)]

crates/admin/src/rest_api/version.rs

@@ -39,5 +39,6 @@ pub async fn version() -> Json<VersionInformation> {
                 .ingress
                 .advertised_address(tc.address_book())
         })),
+        features: Configuration::pinned().common.experimental.features(),
     })
 }

crates/ingress-http/src/handler/service_handler.rs

@@ -140,7 +140,12 @@ where
         };
 
         // Scoped invocations require vqueues to be enabled
-        if scope.is_some() && !Configuration::pinned().common.experimental_enable_vqueues {
+        if scope.is_some()
+            && !Configuration::pinned()
+                .common
+                .experimental
+                .is_vqueues_enabled()
+        {
             return Err(HandlerError::ScopeRequiresVQueues);
         }
 

crates/invoker-impl/src/lib.rs

@@ -257,7 +257,8 @@ impl<StorageReader, TEntryEnricher, Schemas> Service<StorageReader, TEntryEnrich
                     action_token_bucket,
                     allow_protocol_v7: Configuration::pinned()
                         .common
-                        .experimental_allow_protocol_v7,
+                        .experimental
+                        .is_protocol_v7_enabled(),
                 },
                 schemas,
                 invocation_tasks: Default::default(),
@@ -1291,7 +1292,8 @@ where
                     // their memory.
                     if Configuration::pinned()
                         .common
-                        .experimental_enable_invoker_yield
+                        .experimental
+                        .is_invoker_yield_enabled()
                     {
                         debug!(
                             restate.invocation.target = %ism.invocation_target,
@@ -3041,7 +3043,7 @@ mod tests {
     async fn yield_flag_enabled_sends_yield_effect() {
         // Enable the experimental yield flag
         let mut config = Configuration::default();
-        config.common.experimental_enable_invoker_yield = true;
+        config.common.experimental.set_invoker_yield(true);
         restate_types::config::set_current_config(config);
 
         let invoker_options = InvokerOptionsBuilder::default()

crates/types/src/config/common.rs

@@ -15,6 +15,7 @@ use std::sync::LazyLock;
 use std::time::Duration;
 
 use enumset::EnumSet;
+use paste::paste;
 use serde::{Deserialize, Serialize};
 use serde_with::serde_as;
 
@@ -463,20 +464,6 @@ pub struct CommonOptions {
     #[serde(flatten)]
     pub gossip: GossipOptions,
 
-    /// Current in heavy development, do not enable this feature unless you are a contributor
-    #[cfg_attr(feature = "schemars", schemars(skip))]
-    #[serde(skip_serializing_if = "std::ops::Not::not", default)]
-    pub experimental_enable_vqueues: bool,
-
-    /// When enabled, invocations that exhaust their memory budget will yield back to
-    /// the scheduler instead of consuming retry attempts. Requires all nodes in the
-    /// cluster to be running v1.7.0 or later because it introduces a new WAL variant.
-    ///
-    /// Since v1.6.3
-    #[cfg_attr(feature = "schemars", schemars(skip))]
-    #[serde(skip_serializing_if = "std::ops::Not::not", default)]
-    pub experimental_enable_invoker_yield: bool,
-
     /// # HLC maximum drift
     ///
     /// Restate uses an internal hybrid-logical-clock (HLC) to track causality between
@@ -494,6 +481,103 @@ pub struct CommonOptions {
     #[serde(default)]
     hlc_max_drift: FriendlyDuration,
 
+    #[serde(flatten)]
+    pub experimental: Experimental,
+}
+
+/// Declares the [`Experimental`] feature-flag struct from a list of feature names.
+///
+/// Each entry is a bare identifier (optionally preceded by doc comments / attributes) inside
+/// `experimental! { ... }`. For a feature `foo` the macro generates:
+/// - a `experimental_enable_foo: bool` field on [`Experimental`] — this is the on-disk /
+///   JSON-schema name, so the configuration schema always exposes flags as
+///   `experimental_enable_<feature>`;
+/// - `Experimental::is_foo_enabled()` and `Experimental::set_foo(enable)` accessors;
+/// - an entry in [`Experimental::features`] keyed on the bare name `"foo"` (without the
+///   `experimental_enable_` prefix), which is what is surfaced through the admin `/version` API.
+///
+/// Adding a new experimental flag is therefore a one-line change at the invocation site below:
+/// no other code needs to be touched for the flag to show up in `/version`.
+macro_rules! experimental {
+    (@gen_struct [] -> [$($body:tt)*]) => {
+        #[derive(Debug, Clone, Default, Serialize, Deserialize)]
+        #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+        #[cfg_attr(feature = "schemars", schemars(default))]
+        #[serde(rename_all = "kebab-case")]
+        pub struct Experimental {
+            $($body)*
+        }
+    };
+    (@gen_struct [$(#[$($attrss:meta)*])* $feat:ident $(, $($tail:tt)*)?] -> [$($body:tt)*]) => {
+        paste!{
+            experimental!(@gen_struct [$($($tail)*)?] -> [
+                $($body)*
+
+                $(#[$($attrss)*])*
+                #[cfg_attr(feature = "schemars", schemars(skip))]
+                #[serde(skip_serializing_if = "std::ops::Not::not", default)]
+                [<experimental_enable_ $feat>]: bool,
+            ]);
+        }
+    };
+    (@gen_features [] -> [$($field:ident)*]) => {
+        impl Experimental {
+            pub fn features(&self) -> std::collections::HashMap<std::borrow::Cow<'static, str>, bool> {
+                let mut map = std::collections::HashMap::default();
+                $(
+                    paste!{
+                        map.insert(std::borrow::Cow::Borrowed(stringify!($field)), self.[<experimental_enable_ $field>]);
+                    }
+                )*
+                map
+            }
+        }
+    };
+    (@gen_features [$(#[$($attrss:meta)*])* $feat:ident $(, $($tail:tt)*)?] -> [$($acc:ident)*]) => {
+        experimental!(@gen_features [$($($tail)*)?] -> [$($acc)* $feat]);
+    };
+    (@gen_getters [] -> [$($field:ident)*]) => {
+        impl Experimental {
+            $(
+                paste!{
+                    pub fn [<is_ $field _enabled>](&self) -> bool {
+                        self.[<experimental_enable_ $field>]
+                    }
+
+                    pub fn [<set_ $field>](&mut self, enable: bool) {
+                        self.[<experimental_enable_ $field>] = enable;
+                    }
+                }
+            )*
+        }
+    };
+    (@gen_getters [$(#[$($attrss:meta)*])* $feat:ident $(, $($tail:tt)*)?] -> [$($acc:ident)*]) => {
+        experimental!(@gen_getters [$($($tail)*)?] -> [$($acc)* $feat]);
+    };
+
+
+    {$($tokens:tt)*} => {
+        experimental!(@gen_struct [$($tokens)*] -> []);
+        experimental!(@gen_features [$($tokens)*] -> []);
+        experimental!(@gen_getters [$($tokens)*] -> []);
+    };
+}
+
+// List of experimental features. Add a new identifier below to introduce a flag; the
+// `experimental!` macro will generate the `experimental_enable_<name>` config field, the
+// `is_<name>_enabled()` / `set_<name>()` accessors, and the entry exposed (under the bare
+// name, without the `experimental_enable_` prefix) by the admin `/version` API.
+experimental! {
+    /// Current in heavy development, do not enable this feature unless you are a contributor
+    vqueues,
+
+    /// When enabled, invocations that exhaust their memory budget will yield back to
+    /// the scheduler instead of consuming retry attempts. Requires all nodes in the
+    /// cluster to be running v1.7.0 or later because it introduces a new WAL variant.
+    ///
+    /// Since v1.6.3
+    invoker_yield,
+
     /// # Enables service protocol v7
     ///
     /// Introduced in Restate v1.7
@@ -502,9 +586,7 @@ pub struct CommonOptions {
     ///
     /// Once enabled, you **cannot** rollback back to previous versions
     /// where v7 is not supported < v1.7
-    #[cfg_attr(feature = "schemars", schemars(skip))]
-    #[serde(skip_serializing_if = "std::ops::Not::not", default)]
-    pub experimental_allow_protocol_v7: bool,
+    protocol_v7,
 }
 
 serde_with::with_prefix!(pub prefix_tokio_console "tokio_console_");
@@ -740,10 +822,8 @@ impl Default for CommonOptions {
             initialization_timeout: NonZeroFriendlyDuration::from_secs_unchecked(5 * 60),
             disable_telemetry: false,
             gossip: GossipOptions::default(),
-            experimental_enable_vqueues: false,
-            experimental_enable_invoker_yield: false,
             hlc_max_drift: FriendlyDuration::from_millis(5000),
-            experimental_allow_protocol_v7: false,
+            experimental: Experimental::default(),
         }
     }
 }

crates/worker/src/partition/leadership/mod.rs

@@ -456,7 +456,7 @@ where
                 })?
                 .into_guard();
 
-            let scheduler_service = if config.common.experimental_enable_vqueues {
+            let scheduler_service = if config.common.experimental.is_vqueues_enabled() {
                 SchedulerService::create(
                     ResourceManager::create(
                         partition_store.partition_db().clone(),

crates/worker/src/partition/state_machine/lifecycle/paused.rs

@@ -65,7 +65,11 @@ where
         // Invoker paused the invocation, let's record the event, then set the status to paused
         debug_if_leader!(ctx.is_leader, "Paused the invocation");
 
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             // todo: use the new status
             let entry_id = EntryId::from(&invocation_id);
             let Some(header) = ctx

crates/worker/src/partition/state_machine/lifecycle/resume.rs

@@ -41,7 +41,11 @@ where
 
         metadata.timestamps.update(ctx.record_created_at);
 
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             ctx.vqueue_move_invocation_to_inbox_stage(&self.invocation_id)
                 .await?;
         } else {

crates/worker/src/partition/state_machine/lifecycle/suspend.rs

@@ -109,7 +109,11 @@ where
                 .timestamps
                 .update(ctx.record_created_at);
 
-            if Configuration::pinned().common.experimental_enable_vqueues {
+            if Configuration::pinned()
+                .common
+                .experimental
+                .is_vqueues_enabled()
+            {
                 let now = UniqueTimestamp::from_unix_millis_unchecked(ctx.record_created_at);
                 let entry_id = EntryId::from(&self.invocation_id);
                 let Some(header) = ctx

crates/worker/src/partition/state_machine/mod.rs

@@ -849,7 +849,11 @@ impl<S> StateMachineApplyContext<'_, S> {
                 });
         }
 
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             // skips the rest of this logic and jumps straight to vqueues' implementation
             return self
                 .vqueue_enqueue(
@@ -1440,7 +1444,11 @@ impl<S> StateMachineApplyContext<'_, S> {
             + WriteLockTable
             + ReadVQueueTable,
     {
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             self.vqueue_enqueue_state_mutation(mutation).await?;
         } else {
             let service_status = self
@@ -1779,7 +1787,11 @@ impl<S> StateMachineApplyContext<'_, S> {
             Some(&invocation_target),
         )?;
 
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             let record_unique_ts =
                 UniqueTimestamp::from_unix_millis_unchecked(self.record_created_at);
             let new_status = match termination_flavor {
@@ -1892,7 +1904,11 @@ impl<S> StateMachineApplyContext<'_, S> {
             Some(&invocation_target),
         )?;
 
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             let record_unique_ts =
                 UniqueTimestamp::from_unix_millis_unchecked(self.record_created_at);
             let new_status = match termination_flavor {
@@ -2758,7 +2774,11 @@ impl<S> StateMachineApplyContext<'_, S> {
             .await?;
         }
 
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             if invocation_target.invocation_target_ty()
                 == InvocationTargetType::VirtualObject(VirtualObjectHandlerType::Exclusive)
             {
@@ -3109,7 +3129,11 @@ impl<S> StateMachineApplyContext<'_, S> {
             + WriteJournalTable
             + journal_table_v2::WriteJournalTable,
     {
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             return Ok(());
         }
 
@@ -4488,7 +4512,11 @@ impl<S> StateMachineApplyContext<'_, S> {
             .put_invocation_status(&invocation_id, &InvocationStatus::Invoked(metadata))
             .map_err(Error::Storage)?;
 
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             self.vqueue_move_invocation_to_inbox_stage(&invocation_id)
                 .await?;
         } else {
@@ -4529,7 +4557,11 @@ impl<S> StateMachineApplyContext<'_, S> {
 
         metadata.timestamps.update(self.record_created_at);
 
-        if Configuration::pinned().common.experimental_enable_vqueues {
+        if Configuration::pinned()
+            .common
+            .experimental
+            .is_vqueues_enabled()
+        {
             let now = UniqueTimestamp::from_unix_millis_unchecked(self.record_created_at);
             let entry_id = EntryId::from(&invocation_id);
             let Some(header) = self