From c22eebe24a2d3617ae3ea83023b7288c3f23dd0c Mon Sep 17 00:00:00 2001 From: Bill Fraser Date: Sun, 12 Jan 2025 22:59:02 -0800 Subject: [PATCH 1/3] small documentation fixes --- src/async_client_trait.rs | 2 +- src/client_helpers.rs | 10 +++++----- src/client_trait.rs | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/async_client_trait.rs b/src/async_client_trait.rs index 3336d36..1d6a237 100644 --- a/src/async_client_trait.rs +++ b/src/async_client_trait.rs @@ -162,7 +162,7 @@ impl HttpClient for T { pub trait NoauthClient: HttpClient {} /// Marker trait to indicate that a HTTP client supports User authentication. -/// Team authentication works by adding a `Authorization: Bearer ` header. +/// User authentication works by adding a `Authorization: Bearer ` header. pub trait UserAuthClient: HttpClient {} /// Marker trait to indicate that a HTTP client supports Team authentication. diff --git a/src/client_helpers.rs b/src/client_helpers.rs index bb17bd5..f25b43b 100644 --- a/src/client_helpers.rs +++ b/src/client_helpers.rs @@ -117,10 +117,10 @@ pub(crate) async fn body_to_string( } } -/// Does the request and returns a two-level result. The outer result has an error if something -/// went wrong in the process of making the request (I/O errors, parse errors, server 500 errors, -/// etc.). The inner result has an error if the server returned one for the request, otherwise it -/// has the deserialized JSON response and the body stream (if any). +/// Does the request and returns a parsed result, including the response body, if any. If the +/// request is successful, the JSON response is parsed as a `TResponse`. If the result is a HTTP +/// 409 error, the response is parsed as the specified error type `TError` and returned as a +/// [`Error::Api`]. #[allow(clippy::too_many_arguments)] pub async fn request_with_body( client: &TClient, @@ -199,7 +199,7 @@ where if status == 409 { // Response should be JSON-deseraializable into the strongly-typed - // error specified by type parameter E. + // error specified by type parameter TError. return match serde_json::from_str::>(&json) { Ok(deserialized) => { error!("API error: {}", deserialized.error); diff --git a/src/client_trait.rs b/src/client_trait.rs index e8641a7..cb5a938 100644 --- a/src/client_trait.rs +++ b/src/client_trait.rs @@ -46,7 +46,7 @@ pub trait HttpClient: Sync { pub trait NoauthClient: HttpClient {} /// Marker trait to indicate that a HTTP client supports User authentication. -/// Team authentication works by adding a `Authorization: Bearer ` header. +/// User authentication works by adding a `Authorization: Bearer ` header. pub trait UserAuthClient: HttpClient {} /// Marker trait to indicate that a HTTP client supports Team authentication. From f7f8751f9f7f22051875dbf5a922c4f9ee924d0c Mon Sep 17 00:00:00 2001 From: Bill Fraser Date: Mon, 13 Jan 2025 10:49:53 -0800 Subject: [PATCH 2/3] pub(crate) inside a non-public module is unnecessary just use pub instead --- src/client_helpers.rs | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/src/client_helpers.rs b/src/client_helpers.rs index f25b43b..fda5e81 100644 --- a/src/client_helpers.rs +++ b/src/client_helpers.rs @@ -16,7 +16,7 @@ use std::sync::Arc; /// When Dropbox returns an error with HTTP 409 or 429, it uses an implicit JSON object with the /// following structure, which contains the actual error as a field. #[derive(Debug, Deserialize)] -pub(crate) struct TopLevelError { +struct TopLevelError { pub error: T, // It also has these fields, which we don't expose anywhere: //pub error_summary: String, @@ -35,7 +35,7 @@ struct RateLimitedError { } #[allow(clippy::too_many_arguments)] -pub(crate) fn prepare_request( +pub fn prepare_request( client: &T, endpoint: Endpoint, style: Style, @@ -101,9 +101,7 @@ pub(crate) fn prepare_request( (req, params_body) } -pub(crate) async fn body_to_string( - body: &mut (dyn AsyncRead + Send + Unpin), -) -> Result { +async fn body_to_string(body: &mut (dyn AsyncRead + Send + Unpin)) -> Result { let mut s = String::new(); match body.read_to_string(&mut s).await { Ok(_) => Ok(s), @@ -223,7 +221,7 @@ where } } -pub(crate) async fn parse_response( +pub async fn parse_response( raw_resp: HttpRequestResultRaw, style: Style, ) -> Result< @@ -309,7 +307,7 @@ pub(crate) async fn parse_response( } #[derive(Debug, Clone)] -pub(crate) enum Body<'a> { +pub enum Body<'a> { #[cfg(feature = "sync_routes")] Borrowed(&'a [u8]), @@ -332,6 +330,10 @@ impl<'a> From<&'a [u8]> for Body<'a> { } } +/// Does the request and returns a parsed result. If the request is successful, the JSON response +/// is parsed as a `TResponse`. If the result is a HTTP +/// 409 error, the response is parsed as the specified error type `TError` and returned as a +/// [`Error::Api`]. pub async fn request( client: &TClient, endpoint: Endpoint, @@ -364,9 +366,8 @@ mod sync_helpers { /// /// This is ONLY safe if the result was created by a sync HttpClient, so we require it as an /// argument just to be extra careful. - #[cfg(feature = "sync_routes")] #[inline] - pub(crate) fn unwrap_async_result( + fn unwrap_async_result( r: HttpRequestResult, _client: &impl sync::HttpClient, ) -> sync::HttpRequestResult { @@ -391,9 +392,8 @@ mod sync_helpers { } } - #[cfg(feature = "sync_routes")] #[inline] - pub(crate) fn unwrap_async_body( + pub fn unwrap_async_body( f: impl Future, Error>>, client: &impl sync::HttpClient, ) -> Result, Error> { @@ -406,15 +406,12 @@ mod sync_helpers { } } - #[cfg(feature = "sync_routes")] #[inline] - pub(crate) fn unwrap_async( - f: impl Future>>, - ) -> Result> { + pub fn unwrap_async(f: impl Future>>) -> Result> { f.now_or_never() .expect("sync future should resolve immediately") } } #[cfg(feature = "sync_routes")] -pub(crate) use sync_helpers::*; +pub use sync_helpers::*; From cb9e9c2723f81bdf204b719f08488754f8abcf68 Mon Sep 17 00:00:00 2001 From: Bill Fraser Date: Mon, 13 Jan 2025 10:50:27 -0800 Subject: [PATCH 3/3] exclude generated code from rustfmt using attribute instead of deleting it before running cargo fmt --- .github/workflows/cargo-test.yml | 5 ----- src/lib.rs | 1 + tests/generated_tests.rs | 1 + 3 files changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/cargo-test.yml b/.github/workflows/cargo-test.yml index 20ac80e..8bbcbf7 100644 --- a/.github/workflows/cargo-test.yml +++ b/.github/workflows/cargo-test.yml @@ -19,14 +19,9 @@ jobs: rustup component add rustfmt --toolchain nightly - name: Run rustfmt - # Delete the generated code so it doesn't get formatted. - # We'll be re-running the generator later, so this is okay. run: | - rm -rf src/generated - echo "// empty module for rustfmt" > src/generated.rs echo "// empty module for rustfmt" > tests/generated.rs rustup run nightly cargo fmt --check - rm src/generated.rs rm tests/generated.rs - name: Set up Python diff --git a/src/lib.rs b/src/lib.rs index 4fd9943..b190ca3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -56,6 +56,7 @@ mod client_helpers; pub mod oauth2; // You need to run the Stone generator to create this module. +#[rustfmt::skip] mod generated; pub use generated::*; diff --git a/tests/generated_tests.rs b/tests/generated_tests.rs index 764fde3..c0093fb 100644 --- a/tests/generated_tests.rs +++ b/tests/generated_tests.rs @@ -1,3 +1,4 @@ #![warn(rust_2018_idioms)] +#[rustfmt::skip] mod generated; // You need to run the Stone generator to create this module.