Generate beta and experimental APIs, guarded by Cargo features

Author: swallez

api_generator/src/generator/code_gen/namespace_clients.rs

@@ -28,12 +28,15 @@ use std::path::PathBuf;
 pub fn generate(api: &Api, docs_dir: &PathBuf) -> Result<Vec<(String, String)>, failure::Error> {
     let mut output = Vec::new();
 
-    for (namespace, namespace_methods) in &api.namespaces {
+    for (namespace_name, namespace) in &api.namespaces {
         let mut tokens = Tokens::new();
+        if let Some(attr) = namespace.stability.inner_cfg_attr() {
+            tokens.append(attr);
+        }
         tokens.append(use_declarations());
 
-        let namespace_pascal_case = namespace.to_pascal_case();
-        let namespace_replaced_pascal_case = namespace.replace("_", " ").to_pascal_case();
+        let namespace_pascal_case = namespace_name.to_pascal_case();
+        let namespace_replaced_pascal_case = namespace_name.replace("_", " ").to_pascal_case();
         let namespace_client_name = ident(&namespace_pascal_case);
         let name_for_docs = match namespace_replaced_pascal_case.as_ref() {
             "Ccr" => "Cross Cluster Replication",
@@ -53,9 +56,10 @@ pub fn generate(api: &Api, docs_dir: &PathBuf) -> Result<Vec<(String, String)>,
             "Creates a new instance of [{}]",
             &namespace_pascal_case
         ));
-        let namespace_name = ident(namespace.to_string());
+        let namespace_name = ident(namespace_name.to_string());
 
-        let (builders, methods): (Vec<Tokens>, Vec<Tokens>) = namespace_methods
+        let (builders, methods): (Vec<Tokens>, Vec<Tokens>) = namespace
+            .endpoints()
             .iter()
             .map(|(name, endpoint)| {
                 let builder_name = format!("{}{}", &namespace_pascal_case, name.to_pascal_case());
@@ -72,14 +76,17 @@ pub fn generate(api: &Api, docs_dir: &PathBuf) -> Result<Vec<(String, String)>,
             })
             .unzip();
 
+        let cfg_attr = namespace.stability.outer_cfg_attr();
         tokens.append(quote!(
             #(#builders)*
 
             #namespace_doc
+            #cfg_attr
             pub struct #namespace_client_name<'a> {
                 transport: &'a Transport
             }
 
+            #cfg_attr
             impl<'a> #namespace_client_name<'a> {
                 #new_namespace_client_doc
                 pub fn new(transport: &'a Transport) -> Self {
@@ -95,6 +102,7 @@ pub fn generate(api: &Api, docs_dir: &PathBuf) -> Result<Vec<(String, String)>,
                 #(#methods)*
             }
 
+            #cfg_attr
             impl Elasticsearch {
                 #namespace_fn_doc
                 pub fn #namespace_name(&self) -> #namespace_client_name {
@@ -104,7 +112,7 @@ pub fn generate(api: &Api, docs_dir: &PathBuf) -> Result<Vec<(String, String)>,
         ));
 
         let generated = tokens.to_string();
-        output.push((namespace.to_string(), generated));
+        output.push((namespace_name.to_string(), generated));
     }
 
     Ok(output)

api_generator/src/generator/code_gen/params.rs

@@ -64,7 +64,10 @@ fn generate_param(tokens: &mut Tokens, e: &ApiEnum) {
         None => None,
     };
 
+    let cfg_attr = e.stability.outer_cfg_attr();
+
     let generated_enum_tokens = quote!(
+        #cfg_attr
         #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
         #doc
         pub enum #name {

api_generator/src/generator/code_gen/request/request_builder.rs

@@ -626,19 +626,25 @@ impl<'a> RequestBuilder<'a> {
             api_name_for_docs
         ));
 
+        let cfg_attr = endpoint.stability.outer_cfg_attr();
+
         quote! {
+            #cfg_attr
             #enum_struct
 
+            #cfg_attr
             #enum_impl
 
             #[derive(Clone, Debug)]
             #[doc = #builder_doc]
+            #cfg_attr
             pub struct #builder_expr {
                 transport: &'a Transport,
                 parts: #enum_ty,
                 #(#fields),*,
             }
 
+            #cfg_attr
             #builder_impl {
                 #new_fn
                 #(#builder_fns)*
@@ -669,6 +675,8 @@ impl<'a> RequestBuilder<'a> {
         is_root_method: bool,
         enum_builder: &EnumBuilder,
     ) -> Tokens {
+        let cfg_attr = endpoint.stability.outer_cfg_attr();
+
         let builder_ident = ident(builder_name);
 
         let (fn_name, builder_ident_ret) = {
@@ -726,6 +734,7 @@ impl<'a> RequestBuilder<'a> {
         if enum_builder.contains_single_parameterless_part() {
             quote!(
                 #method_doc
+                #cfg_attr
                 pub fn #fn_name(&'a self) -> #builder_ident_ret {
                     #builder_ident::new(#clone_expr)
                 }
@@ -734,6 +743,7 @@ impl<'a> RequestBuilder<'a> {
             let (enum_ty, _, _) = enum_builder.clone().build();
             quote!(
                 #method_doc
+                #cfg_attr
                 pub fn #fn_name(&'a self, parts: #enum_ty) -> #builder_ident_ret {
                     #builder_ident::new(#clone_expr, parts)
                 }

api_generator/src/generator/code_gen/root.rs

@@ -32,6 +32,7 @@ pub fn generate(api: &Api, docs_dir: &PathBuf) -> Result<String, failure::Error>
     // AST for builder structs and methods
     let (builders, methods): (Vec<Tokens>, Vec<Tokens>) = api
         .root
+        .endpoints()
         .iter()
         .map(|(name, endpoint)| {
             let builder_name = name.to_pascal_case();

api_generator/src/generator/code_gen/url/enum_builder.rs

@@ -311,7 +311,7 @@ mod tests {
     #![cfg_attr(rustfmt, rustfmt_skip)]
 
     use super::*;
-    use crate::generator::{Url, Path, HttpMethod, Body, Deprecated, Type, TypeKind, Documentation, ast_eq};
+    use crate::generator::{Url, Path, HttpMethod, Body, Deprecated, Type, TypeKind, Documentation, ast_eq, Stability};
     use std::collections::BTreeMap;
     use crate::generator::code_gen::url::url_builder::PathString;
 
@@ -326,7 +326,7 @@ mod tests {
                     description: None,
                     url: None,
                 },
-                stability: "stable".to_string(),
+                stability: Stability::Stable,
                 url: Url {
                     paths: vec![
                         Path {

api_generator/src/generator/mod.rs

@@ -34,7 +34,8 @@ use std::{
 };
 
 #[cfg(test)]
-use quote::{ToTokens, Tokens};
+use quote::ToTokens;
+use quote::Tokens;
 use semver::Version;
 use void::Void;
 
@@ -63,9 +64,9 @@ pub struct Api {
     /// parameters that are common to all API methods
     pub common_params: BTreeMap<String, Type>,
     /// root API methods e.g. Search, Index
-    pub root: BTreeMap<String, ApiEndpoint>,
+    pub root: ApiNamespace,
     /// namespace client methods e.g. Indices.Create, Ml.PutJob
-    pub namespaces: BTreeMap<String, BTreeMap<String, ApiEndpoint>>,
+    pub namespaces: BTreeMap<String, ApiNamespace>,
     /// enums in parameters
     pub enums: Vec<ApiEnum>,
 }
@@ -79,9 +80,9 @@ impl Api {
     pub fn endpoint_for_api_call(&self, api_call: &str) -> Option<&ApiEndpoint> {
         let api_call_path: Vec<&str> = api_call.split('.').collect();
         match api_call_path.len() {
-            1 => self.root.get(api_call_path[0]),
+            1 => self.root.endpoints().get(api_call_path[0]),
             _ => match self.namespaces.get(api_call_path[0]) {
-                Some(namespace) => namespace.get(api_call_path[1]),
+                Some(namespace) => namespace.endpoints().get(api_call_path[1]),
                 None => None,
             },
         }
@@ -347,13 +348,49 @@ where
     deserializer.deserialize_any(StringOrStruct(PhantomData))
 }
 
+/// Stability level of an API endpoint. Ordering defines increasing stability level, i.e.
+/// `beta` is "more stable" than `experimental`.
+#[derive(Debug, Eq, PartialEq, Deserialize, Clone, Copy, Ord, PartialOrd)]
+pub enum Stability {
+    #[serde(rename = "experimental")]
+    Experimental,
+    #[serde(rename = "beta")]
+    Beta,
+    #[serde(rename = "stable")]
+    Stable,
+}
+
+impl Stability {
+    pub fn feature_name(self) -> Option<&'static str> {
+        match self {
+            Stability::Experimental => Some("experimental-apis"),
+            Stability::Beta => Some("beta-apis"),
+            Stability::Stable => None,
+        }
+    }
+
+    /// Returns the (optional) feature configuration for this stability level as an outer
+    /// attribute, for use e.g. on function definitions.
+    pub fn outer_cfg_attr(self) -> Option<Tokens> {
+        let feature_name = self.feature_name();
+        feature_name.map(|name| quote!(#[cfg(feature = #name)]))
+    }
+
+    /// Returns the (optional) feature configuration for this stability level as an inner
+    /// attribute, for use e.g. at the top of a module source file
+    pub fn inner_cfg_attr(self) -> Option<Tokens> {
+        let feature_name = self.feature_name();
+        feature_name.map(|name| quote!(#![cfg(feature = #name)]))
+    }
+}
+
 /// An API endpoint defined in the REST API specs
 #[derive(Debug, PartialEq, Deserialize, Clone)]
 pub struct ApiEndpoint {
     pub full_name: Option<String>,
     #[serde(deserialize_with = "string_or_struct")]
     documentation: Documentation,
-    pub stability: String,
+    pub stability: Stability,
     pub url: Url,
     #[serde(default = "BTreeMap::new")]
     pub params: BTreeMap<String, Type>,
@@ -382,6 +419,34 @@ impl ApiEndpoint {
     }
 }
 
+pub struct ApiNamespace {
+    stability: Stability,
+    endpoints: BTreeMap<String, ApiEndpoint>,
+}
+
+impl ApiNamespace {
+    pub fn new() -> Self {
+        ApiNamespace {
+            stability: Stability::Experimental, // will grow in stability as we add endpoints
+            endpoints: BTreeMap::new(),
+        }
+    }
+
+    pub fn add(&mut self, name: String, endpoint: ApiEndpoint) {
+        // Stability of a namespace is that of the most stable of its endpoints
+        self.stability = Stability::max(self.stability, endpoint.stability);
+        self.endpoints.insert(name, endpoint);
+    }
+
+    pub fn stability(&self) -> Stability {
+        self.stability
+    }
+
+    pub fn endpoints(&self) -> &BTreeMap<String, ApiEndpoint> {
+        &self.endpoints
+    }
+}
+
 /// Common parameters accepted by all API endpoints
 #[derive(Debug, PartialEq, Deserialize, Clone)]
 pub struct Common {
@@ -396,6 +461,7 @@ pub struct ApiEnum {
     pub name: String,
     pub description: Option<String>,
     pub values: Vec<String>,
+    pub stability: Stability, // inherited from the declaring API
 }
 
 impl Hash for ApiEnum {
@@ -499,7 +565,7 @@ pub use bulk::*;
 /// Reads Api from a directory of REST Api specs
 pub fn read_api(branch: &str, download_dir: &PathBuf) -> Result<Api, failure::Error> {
     let paths = fs::read_dir(download_dir)?;
-    let mut namespaces = BTreeMap::new();
+    let mut namespaces = BTreeMap::<String, ApiNamespace>::new();
     let mut enums: HashSet<ApiEnum> = HashSet::new();
     let mut common_params = BTreeMap::new();
     let root_key = "root";
@@ -517,11 +583,6 @@ pub fn read_api(branch: &str, download_dir: &PathBuf) -> Result<Api, failure::Er
             let mut file = File::open(&path)?;
             let (name, api_endpoint) = endpoint_from_file(display, &mut file)?;
 
-            // Only generate builders and methods for stable APIs, not experimental or beta
-            if &api_endpoint.stability != "stable" {
-                continue;
-            }
-
             let name_parts: Vec<&str> = name.splitn(2, '.').collect();
             let (namespace, method_name) = match name_parts.len() {
                 len if len > 1 => (name_parts[0].to_string(), name_parts[1].to_string()),
@@ -545,19 +606,20 @@ pub fn read_api(branch: &str, download_dir: &PathBuf) -> Result<Api, failure::Er
                     name: param.0.to_string(),
                     description: param.1.description.clone(),
                     values: options,
+                    stability: api_endpoint.stability,
                 });
             }
 
             // collect api endpoints into namespaces
             if !namespaces.contains_key(&namespace) {
-                let mut api_endpoints = BTreeMap::new();
-                api_endpoints.insert(method_name, api_endpoint);
-                namespaces.insert(namespace.to_string(), api_endpoints);
+                let mut api_namespace = ApiNamespace::new();
+                api_namespace.add(method_name, api_endpoint);
+                namespaces.insert(namespace.to_string(), api_namespace);
             } else {
                 namespaces
                     .get_mut(&namespace)
                     .unwrap()
-                    .insert(method_name, api_endpoint);
+                    .add(method_name, api_endpoint);
             }
         } else if name
             .map(|name| name == Some("_common.json"))
@@ -627,3 +689,14 @@ where
 pub fn ast_eq<T: ToTokens>(expected: Tokens, actual: T) {
     assert_eq!(expected, quote!(#actual));
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn stability_ordering() {
+        assert!(Stability::Beta > Stability::Experimental);
+        assert!(Stability::Stable > Stability::Beta);
+    }
+}

elasticsearch/Cargo.toml

@@ -17,6 +17,10 @@ all-features = true
 [features]
 default = ["native-tls"]
 
+# beta and experimental APIs
+beta-apis = []
+experimental-apis = ["beta-apis"]
+
 # optional TLS
 native-tls = ["reqwest/native-tls"]
 rustls-tls = ["reqwest/rustls-tls"]

yaml_test_runner/Cargo.toml

@@ -9,7 +9,7 @@ repository = "https://github.com/elastic/elasticsearch-rs"
 license = "Apache-2.0"
 
 [dependencies]
-elasticsearch = { path = "./../elasticsearch" }
+elasticsearch = { path = "./../elasticsearch", features = ["experimental-apis"]}
 api_generator = { path = "./../api_generator" }
 
 base64 = "^0.11"