Use re-exports to make depending on propolis-client less cumbersome

Author: lif

Cargo.lock

@@ -35,23 +35,6 @@ You'll need to add add the following to `Cargo.toml`:
 ```diff
 [dependencies]
 +progenitor = { git = "https://github.com/oxidecomputer/progenitor" }
-+reqwest = { version = "0.11", features = ["json", "stream"] }
-+serde = { version = "1.0", features = ["derive"] }
-```
-
-In addition, if the OpenAPI document contains string types with the `format`
-field set to `date` or `date-time`, include
-
-```diff
-[dependencies]
-+chrono = { version = "0.4", features = ["serde"] }
-```
-
-Similarly if there is a `format` field set to `uuid`:
-
-```diff
-[dependencies]
-+uuid = { version = "1.0.0", features = ["serde", "v4"] }
 ```
 
 The macro has some additional fancy options to control the generated code:
@@ -108,20 +91,15 @@ You'll need to add add the following to `Cargo.toml`:
 ```diff
 [dependencies]
 +progenitor-client = { git = "https://github.com/oxidecomputer/progenitor" }
-+reqwest = { version = "0.11", features = ["json", "stream"] }
-+serde = { version = "1.0", features = ["derive"] }
 
 [build-dependencies]
 +progenitor = { git = "https://github.com/oxidecomputer/progenitor" }
 +serde_json = "1.0"
 ```
 
-(`chrono` and `uuid` as above)
-
 Note that `progenitor` is used by `build.rs`, but the generated code required
 `progenitor-client`.
 
-
 ### Static Crate
 
 Progenitor can be run to emit a stand-alone crate for the generated client.
@@ -146,14 +124,14 @@ For example:
 
 This will produce a package in the specified directory. The output has no
 persistent dependency on Progenitor including the `progenitor-client` crate.
-Here's a excerpt from the emitted `Cargo.toml`:
+Here's an excerpt from the emitted `Cargo.toml`:
 
 ```toml
 [dependencies]
 chrono = { version = "0.4", features = ["serde"] }
 futures = "0.3"
 percent-encoding = "2.1"
-reqwest = { version = "0.11", features = ["json", "stream"] }
+reqwest = { git = "https://github.com/seanmonstar/reqwest", rev = "6ceb23958c8b6d7f1d8ee093f0ad73184d133d40", features = ["json", "stream"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 uuid = { version = ">=0.8.0, <2.0.0", features = ["serde", "v4"] }
@@ -162,6 +140,11 @@ uuid = { version = ">=0.8.0, <2.0.0", features = ["serde", "v4"] }
 Note that there is a dependency on `percent-encoding` which macro- and
 build.rs-generated clients is included from `progenitor-client`.
 
+Additionally, note that `chrono` is only required if the OpenAPI document
+contains string types with the `format` field set to `date` or `date-time`,
+and `uuid` is only required if there is a `format` field set to `uuid`.
+(Similarly, `base64` and `rand` would've been included if the API included
+any endpoints using the nonstandard Dropshot extension for Websockets.)
 
 ## Generation Styles
 
@@ -290,4 +273,4 @@ let result = client
 ```
 
 Consumers do not need to specify parameters and struct properties that are not
-required or for which the API specifies defaults. Neat!
+required or for which the API specifies defaults. Neat!

README.md

@@ -5,10 +5,5 @@ authors = ["Adam H. Leventhal <ahl@oxidecomputer.com>"]
 edition = "2021"
 
 [dependencies]
-chrono = { version = "0.4", features = ["serde"] }
 progenitor = { path = "../progenitor" }
-reqwest = { git = "https://github.com/seanmonstar/reqwest", rev = "6ceb23958c8b6d7f1d8ee093f0ad73184d133d40", features = ["json", "stream"] }
-#reqwest = { version = "0.11", features = ["json", "stream"] }
 schemars = { version = "0.8.10", features = ["uuid1"] }
-serde = { version = "1.0", features = ["derive"] }
-uuid = { version = "1.0", features = ["serde", "v4"] }

example-macro/Cargo.toml

@@ -11,8 +11,9 @@ bytes = "1.2.1"
 futures-core = "0.3.24"
 percent-encoding = "2.2"
 reqwest = { git = "https://github.com/seanmonstar/reqwest", rev = "6ceb23958c8b6d7f1d8ee093f0ad73184d133d40", features = ["json", "stream"] }
-#reqwest = { version = "0.11", default-features = false, features = ["json", "stream"] }
-serde = "1.0"
+chrono = { version = "0.4", features = ["serde"] }
+uuid = { version = "1.0.0", features = ["serde", "v4"] }
+serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 serde_urlencoded = "0.7.1"
 base64 = "0.13"

progenitor-client/Cargo.toml

@@ -4,6 +4,15 @@ mod progenitor_client;
 
 pub use crate::progenitor_client::*;
 
+pub mod deps {
+    pub use ::base64;
+    pub use ::chrono;
+    pub use ::rand;
+    pub use ::reqwest;
+    pub use ::serde;
+    pub use ::uuid;
+}
+
 // For stand-alone crates, rather than adding a dependency on
 // progenitor-client, we simply dump the code right in. This means we don't
 // need to determine the provenance of progenitor (crates.io, github, etc.)

progenitor-client/src/lib.rs

@@ -401,8 +401,3 @@ impl<E> RequestBuilderExt<E> for RequestBuilder {
             })?))
     }
 }
-
-#[doc(hidden)]
-pub fn generate_websocket_key() -> String {
-    base64::encode(rand::random::<[u8; 16]>())
-}

progenitor-client/src/progenitor_client.rs

@@ -21,8 +21,8 @@ serde_json = "1.0"
 syn = { version = "1.0", features = ["parsing"] }
 thiserror = "1.0"
 # To publish, use a numbered version
-typify = "0.0.10"
-#typify = { git = "https://github.com/oxidecomputer/typify" }
+#typify = "0.0.10"
+typify = { git = "https://github.com/oxidecomputer/typify" }
 unicode-ident = "1.0.3"
 
 [dev-dependencies]

progenitor-impl/Cargo.toml

@@ -38,6 +38,7 @@ pub struct Generator {
     type_space: TypeSpace,
     settings: GenerationSettings,
     uses_futures: bool,
+    uses_websockets: bool,
 }
 
 #[derive(Default, Clone)]
@@ -48,6 +49,7 @@ pub struct GenerationSettings {
     pre_hook: Option<TokenStream>,
     post_hook: Option<TokenStream>,
     extra_derives: Vec<String>,
+    serde_crate_location: Option<String>,
 }
 
 #[derive(Clone, Deserialize, PartialEq, Eq)]
@@ -108,6 +110,19 @@ impl GenerationSettings {
         self.extra_derives.push(derive.to_string());
         self
     }
+
+    pub fn with_serde_crate_location(
+        &mut self,
+        crate_location: impl ToString,
+    ) -> &mut Self {
+        self.serde_crate_location = Some(crate_location.to_string());
+        self
+    }
+
+    pub fn without_serde_crate_location(&mut self) -> &mut Self {
+        self.serde_crate_location = None;
+        self
+    }
 }
 
 impl Default for Generator {
@@ -118,6 +133,7 @@ impl Default for Generator {
             ),
             settings: Default::default(),
             uses_futures: Default::default(),
+            uses_websockets: Default::default(),
         }
     }
 }
@@ -128,13 +144,17 @@ impl Generator {
         type_settings
             .with_type_mod("types")
             .with_struct_builder(settings.interface == InterfaceStyle::Builder);
+        if let Some(crate_location) = &settings.serde_crate_location {
+            type_settings.with_serde_crate_location(crate_location.to_owned());
+        }
         settings.extra_derives.iter().for_each(|derive| {
             let _ = type_settings.with_derive(derive.clone());
         });
         Self {
             type_space: TypeSpace::new(&type_settings),
             settings: settings.clone(),
             uses_futures: false,
+            uses_websockets: false,
         }
     }
 
@@ -219,12 +239,13 @@ impl Generator {
                 ByteStream,
                 Error,
                 ResponseValue,
-                generate_websocket_key
             };
             #[allow(unused_imports)]
             use progenitor_client::{encode_path, RequestBuilderExt};
 
             pub mod types {
+                #[allow(unused_imports)]
+                use super::deps::*;
                 use serde::{Deserialize, Serialize};
 
                 // This may be used by some impl Deserialize, but not all.
@@ -325,8 +346,8 @@ impl Generator {
                 use super::types;
                 #[allow(unused_imports)]
                 use super::{
+                    deps::*,
                     encode_path,
-                    generate_websocket_key,
                     ByteStream,
                     Error,
                     RequestBuilderExt,
@@ -363,8 +384,8 @@ impl Generator {
                 use super::types;
                 #[allow(unused_imports)]
                 use super::{
+                    deps::*,
                     encode_path,
-                    generate_websocket_key,
                     ByteStream,
                     Error,
                     RequestBuilderExt,
@@ -388,9 +409,25 @@ impl Generator {
 
     /// Render text output.
     pub fn generate_text(&mut self, spec: &OpenAPI) -> Result<String> {
+        self.settings
+            .with_serde_crate_location("progenitor_client::deps::serde");
         self.generate_text_impl(
             spec,
             rustfmt_wrapper::config::Config::default(),
+            true,
+        )
+    }
+
+    /// Render text output without re-exports (for stand-alone crate output)
+    pub fn generate_text_standalone(
+        &mut self,
+        spec: &OpenAPI,
+    ) -> Result<String> {
+        self.settings.without_serde_crate_location();
+        self.generate_text_impl(
+            spec,
+            rustfmt_wrapper::config::Config::default(),
+            false,
         )
     }
 
@@ -409,15 +446,33 @@ impl Generator {
                 wrap_comments: Some(true),
                 ..Default::default()
             },
+            true,
         )
     }
 
     fn generate_text_impl(
         &mut self,
         spec: &OpenAPI,
         config: rustfmt_wrapper::config::Config,
+        reexport: bool,
     ) -> Result<String> {
-        let output = self.generate_tokens(spec)?;
+        let mut output = self.generate_tokens(spec)?;
+        if reexport {
+            // Add re-exports from progenitor-client such that build.rs users
+            // don't have to maintain a matching dependency on the same reqwest
+            // version we use.
+            output = quote! {
+                use progenitor_client::deps;
+                #output
+            };
+        } else {
+            // the generated output has a couple instances of (in this case
+            // unnecessary) `use super::deps::*;` which we account for with:
+            output = quote! {
+                mod deps { /* this space intentionally left blank */ }
+                #output
+            };
+        }
 
         // Format the file with rustfmt.
         let content = rustfmt_wrapper::rustfmt_config(config, output).unwrap();
@@ -437,7 +492,7 @@ impl Generator {
             "bytes = \"1.1\"",
             "futures-core = \"0.3\"",
             "percent-encoding = \"2.1\"",
-            "reqwest = { version = \"0.11\", features = [\"json\", \"stream\"] }",
+            "reqwest = { git = \"https://github.com/seanmonstar/reqwest\", rev = \"6ceb23958c8b6d7f1d8ee093f0ad73184d133d40\", features = [\"json\", \"stream\"] }",
             "serde = { version = \"1.0\", features = [\"derive\"] }",
             "serde_urlencoded = \"0.7\"",
         ];
@@ -455,6 +510,10 @@ impl Generator {
         if self.uses_futures {
             deps.push("futures = \"0.3\"")
         }
+        if self.uses_websockets {
+            deps.push("base64 = \"0.13\"");
+            deps.push("rand = \"0.8\"");
+        }
         if self.type_space.uses_serde_json() {
             deps.push("serde_json = \"1.0\"")
         }