From 054de1329ef7be0bf3a03bc753e40d727379c6e4 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Thu, 16 Nov 2023 21:28:09 -0600 Subject: [PATCH 01/12] Remove `#[doc(hidden)]` from smithy runtime crates --- .../src/future/pagination_stream/collect.rs | 1 - .../src/client/interceptors/context.rs | 12 +--------- .../src/client/orchestrator.rs | 1 - .../src/client/result.rs | 1 - .../src/client/runtime_plugin.rs | 1 - .../aws-smithy-runtime-api/src/lib.rs | 3 +-- .../aws-smithy-runtime-api/src/macros.rs | 3 --- .../src/client/http/test_util/wire.rs | 1 - .../src/client/orchestrator.rs | 1 - .../src/client/orchestrator/operation.rs | 23 +++++++++++++++++-- .../aws-smithy-runtime/src/client/retries.rs | 4 ++-- .../src/client/retries/client_rate_limiter.rs | 3 ++- .../aws-smithy-types/src/error/metadata.rs | 1 - 13 files changed, 27 insertions(+), 28 deletions(-) diff --git a/rust-runtime/aws-smithy-async/src/future/pagination_stream/collect.rs b/rust-runtime/aws-smithy-async/src/future/pagination_stream/collect.rs index 1a6fcfbf9a..b74e08f735 100644 --- a/rust-runtime/aws-smithy-async/src/future/pagination_stream/collect.rs +++ b/rust-runtime/aws-smithy-async/src/future/pagination_stream/collect.rs @@ -14,7 +14,6 @@ pub(crate) mod sealed { /// /// Currently the trait may not be implemented by clients so we can make changes in the future /// without breaking code depending on it. - #[doc(hidden)] pub trait Collectable { type Collection; diff --git a/rust-runtime/aws-smithy-runtime-api/src/client/interceptors/context.rs b/rust-runtime/aws-smithy-runtime-api/src/client/interceptors/context.rs index b3844f0bf5..31793243b2 100644 --- a/rust-runtime/aws-smithy-runtime-api/src/client/interceptors/context.rs +++ b/rust-runtime/aws-smithy-runtime-api/src/client/interceptors/context.rs @@ -222,7 +222,6 @@ impl InterceptorContext { } /// Advance to the Serialization phase. - #[doc(hidden)] pub fn enter_serialization_phase(&mut self) { debug!("entering \'serialization\' phase"); debug_assert!( @@ -233,7 +232,6 @@ impl InterceptorContext { } /// Advance to the BeforeTransmit phase. - #[doc(hidden)] pub fn enter_before_transmit_phase(&mut self) { debug!("entering \'before transmit\' phase"); debug_assert!( @@ -253,7 +251,6 @@ impl InterceptorContext { } /// Advance to the Transmit phase. - #[doc(hidden)] pub fn enter_transmit_phase(&mut self) { debug!("entering \'transmit\' phase"); debug_assert!( @@ -264,7 +261,6 @@ impl InterceptorContext { } /// Advance to the BeforeDeserialization phase. - #[doc(hidden)] pub fn enter_before_deserialization_phase(&mut self) { debug!("entering \'before deserialization\' phase"); debug_assert!( @@ -283,7 +279,6 @@ impl InterceptorContext { } /// Advance to the Deserialization phase. - #[doc(hidden)] pub fn enter_deserialization_phase(&mut self) { debug!("entering \'deserialization\' phase"); debug_assert!( @@ -294,7 +289,6 @@ impl InterceptorContext { } /// Advance to the AfterDeserialization phase. - #[doc(hidden)] pub fn enter_after_deserialization_phase(&mut self) { debug!("entering \'after deserialization\' phase"); debug_assert!( @@ -309,7 +303,6 @@ impl InterceptorContext { } /// Set the request checkpoint. This should only be called once, right before entering the retry loop. - #[doc(hidden)] pub fn save_checkpoint(&mut self) { trace!("saving request checkpoint..."); self.request_checkpoint = self.request().and_then(|r| r.try_clone()); @@ -320,7 +313,6 @@ impl InterceptorContext { } /// Returns false if rewinding isn't possible - #[doc(hidden)] pub fn rewind(&mut self, _cfg: &mut ConfigBag) -> RewindResult { // If request_checkpoint was never set, but we've already made one attempt, // then this is not a retryable request @@ -351,7 +343,6 @@ where E: Debug, { /// Decomposes the context into its constituent parts. - #[doc(hidden)] #[allow(clippy::type_complexity)] pub fn into_parts( self, @@ -370,7 +361,6 @@ where } /// Convert this context into the final operation result that is returned in client's the public API. - #[doc(hidden)] pub fn finalize(self) -> Result> { let Self { output_or_error, @@ -399,8 +389,8 @@ where } /// The result of attempting to rewind a request. +#[non_exhaustive] #[derive(Debug, PartialEq, Eq, Clone, Copy)] -#[doc(hidden)] pub enum RewindResult { /// The request couldn't be rewound because it wasn't cloneable. Impossible, diff --git a/rust-runtime/aws-smithy-runtime-api/src/client/orchestrator.rs b/rust-runtime/aws-smithy-runtime-api/src/client/orchestrator.rs index de49383e21..873b8a1cc3 100644 --- a/rust-runtime/aws-smithy-runtime-api/src/client/orchestrator.rs +++ b/rust-runtime/aws-smithy-runtime-api/src/client/orchestrator.rs @@ -215,7 +215,6 @@ impl OrchestratorError { } /// Maps the error type in `ErrorKind::Operation` - #[doc(hidden)] pub fn map_operation_error(self, map: impl FnOnce(E) -> E2) -> OrchestratorError { let kind = match self.kind { ErrorKind::Connector { source } => ErrorKind::Connector { source }, diff --git a/rust-runtime/aws-smithy-runtime-api/src/client/result.rs b/rust-runtime/aws-smithy-runtime-api/src/client/result.rs index 93013abdd8..677ba101fd 100644 --- a/rust-runtime/aws-smithy-runtime-api/src/client/result.rs +++ b/rust-runtime/aws-smithy-runtime-api/src/client/result.rs @@ -438,7 +438,6 @@ impl SdkError { } /// Maps the service error type in `SdkError::ServiceError` - #[doc(hidden)] pub fn map_service_error(self, map: impl FnOnce(E) -> E2) -> SdkError { match self { SdkError::ServiceError(context) => SdkError::::ServiceError(ServiceError { diff --git a/rust-runtime/aws-smithy-runtime-api/src/client/runtime_plugin.rs b/rust-runtime/aws-smithy-runtime-api/src/client/runtime_plugin.rs index fa243211fe..757224051d 100644 --- a/rust-runtime/aws-smithy-runtime-api/src/client/runtime_plugin.rs +++ b/rust-runtime/aws-smithy-runtime-api/src/client/runtime_plugin.rs @@ -228,7 +228,6 @@ macro_rules! apply_plugins { } /// Used internally in the orchestrator implementation and in the generated code. Not intended to be used elsewhere. -#[doc(hidden)] #[derive(Default, Clone, Debug)] pub struct RuntimePlugins { client_plugins: Vec, diff --git a/rust-runtime/aws-smithy-runtime-api/src/lib.rs b/rust-runtime/aws-smithy-runtime-api/src/lib.rs index 3a96c8d07a..2741caf8a2 100644 --- a/rust-runtime/aws-smithy-runtime-api/src/lib.rs +++ b/rust-runtime/aws-smithy-runtime-api/src/lib.rs @@ -33,8 +33,7 @@ pub mod client; pub mod http; -/// Internal builder macros. Not intended to be used outside of the aws-smithy-runtime crates. -#[doc(hidden)] +/// Builder macros. Not intended to be used outside of the aws-smithy-runtime crates. pub mod macros; pub mod shared; diff --git a/rust-runtime/aws-smithy-runtime-api/src/macros.rs b/rust-runtime/aws-smithy-runtime-api/src/macros.rs index 759d1b8452..09efd0a74c 100644 --- a/rust-runtime/aws-smithy-runtime-api/src/macros.rs +++ b/rust-runtime/aws-smithy-runtime-api/src/macros.rs @@ -111,7 +111,6 @@ /// } /// } /// ``` -#[doc(hidden)] #[macro_export] macro_rules! builder { ($($tt:tt)+) => { @@ -129,7 +128,6 @@ macro_rules! builder { /// Define a new builder struct, its fields, and their docs. This macro is intended to be called /// by the `builder!` macro and should not be called directly. -#[doc(hidden)] #[macro_export] macro_rules! builder_struct { ($($_setter_name:ident, $field_name:ident, $ty:ty, $doc:literal $(,)?)+) => { @@ -145,7 +143,6 @@ macro_rules! builder_struct { /// Define setter methods for a builder struct. Must be called from within an `impl` block. This /// macro is intended to be called by the `builder!` macro and should not be called directly. -#[doc(hidden)] #[macro_export] macro_rules! builder_methods { ($fn_name:ident, $arg_name:ident, $ty:ty, $doc:literal, $($tail:tt)+) => { diff --git a/rust-runtime/aws-smithy-runtime/src/client/http/test_util/wire.rs b/rust-runtime/aws-smithy-runtime/src/client/http/test_util/wire.rs index e152c9b11c..6c0a619117 100644 --- a/rust-runtime/aws-smithy-runtime/src/client/http/test_util/wire.rs +++ b/rust-runtime/aws-smithy-runtime/src/client/http/test_util/wire.rs @@ -75,7 +75,6 @@ type Matcher = ( ); /// This method should only be used by the macro -#[doc(hidden)] pub fn check_matches(events: &[RecordedEvent], matchers: &[Matcher]) { let mut events_iter = events.iter(); let mut matcher_iter = matchers.iter(); diff --git a/rust-runtime/aws-smithy-runtime/src/client/orchestrator.rs b/rust-runtime/aws-smithy-runtime/src/client/orchestrator.rs index bfff548072..e9fcb66153 100644 --- a/rust-runtime/aws-smithy-runtime/src/client/orchestrator.rs +++ b/rust-runtime/aws-smithy-runtime/src/client/orchestrator.rs @@ -43,7 +43,6 @@ pub mod endpoints; mod http; /// Utility for making one-off unmodeled requests with the orchestrator. -#[doc(hidden)] pub mod operation; macro_rules! halt { diff --git a/rust-runtime/aws-smithy-runtime/src/client/orchestrator/operation.rs b/rust-runtime/aws-smithy-runtime/src/client/orchestrator/operation.rs index bff3cd1f4b..5ae8ab04d8 100644 --- a/rust-runtime/aws-smithy-runtime/src/client/orchestrator/operation.rs +++ b/rust-runtime/aws-smithy-runtime/src/client/orchestrator/operation.rs @@ -104,7 +104,6 @@ impl fmt::Debug for FnDeserializer { } /// Orchestrates execution of a HTTP request without any modeled input or output. -#[doc(hidden)] #[derive(Debug)] pub struct Operation { service_name: Cow<'static, str>, @@ -126,6 +125,7 @@ impl Clone for Operation { } impl Operation<(), (), ()> { + /// Returns a new `OperationBuilder` for the `Operation`. pub fn builder() -> OperationBuilder { OperationBuilder::new() } @@ -137,6 +137,8 @@ where O: fmt::Debug + Send + Sync + 'static, E: std::error::Error + fmt::Debug + Send + Sync + 'static, { + /// Invokes this `Operation` with the given `input` and returns either an output for success + /// or an [`SdkError`] for failure pub async fn invoke(&self, input: I) -> Result> { let input = Input::erase(input); @@ -153,7 +155,7 @@ where } } -#[doc(hidden)] +/// Builder for [`Operation`]. #[derive(Debug)] pub struct OperationBuilder { service_name: Option>, @@ -171,6 +173,7 @@ impl Default for OperationBuilder<(), (), ()> { } impl OperationBuilder<(), (), ()> { + /// Creates a new [`OperationBuilder`]. pub fn new() -> Self { Self { service_name: None, @@ -184,21 +187,25 @@ impl OperationBuilder<(), (), ()> { } impl OperationBuilder { + /// Configures the service name for the builder. pub fn service_name(mut self, service_name: impl Into>) -> Self { self.service_name = Some(service_name.into()); self } + /// Configures the operation name for the builder. pub fn operation_name(mut self, operation_name: impl Into>) -> Self { self.operation_name = Some(operation_name.into()); self } + /// Configures the http client for the builder. pub fn http_client(mut self, connector: impl HttpClient + 'static) -> Self { self.runtime_components.set_http_client(Some(connector)); self } + /// Configures the endpoint URL for the builder. pub fn endpoint_url(mut self, url: &str) -> Self { self.config.store_put(EndpointResolverParams::new(())); self.runtime_components @@ -208,18 +215,21 @@ impl OperationBuilder { self } + /// Configures the retry classifier for the builder. pub fn retry_classifier(mut self, retry_classifier: impl ClassifyRetry + 'static) -> Self { self.runtime_components .push_retry_classifier(retry_classifier); self } + /// Disables the retry for the operation. pub fn no_retry(mut self) -> Self { self.runtime_components .set_retry_strategy(Some(SharedRetryStrategy::new(NeverRetryStrategy::new()))); self } + /// Configures the standard retry for the builder. pub fn standard_retry(mut self, retry_config: &RetryConfig) -> Self { self.config.store_put(retry_config.clone()); self.runtime_components @@ -227,11 +237,13 @@ impl OperationBuilder { self } + /// Configures the timeout configuration for the builder. pub fn timeout_config(mut self, timeout_config: TimeoutConfig) -> Self { self.config.store_put(timeout_config); self } + /// Disables auth for the operation. pub fn no_auth(mut self) -> Self { self.config .store_put(AuthSchemeOptionResolverParams::new(())); @@ -250,18 +262,21 @@ impl OperationBuilder { self } + /// Configures the sleep for the builder. pub fn sleep_impl(mut self, async_sleep: impl AsyncSleep + 'static) -> Self { self.runtime_components .set_sleep_impl(Some(async_sleep.into_shared())); self } + /// Configures the time source for the builder. pub fn time_source(mut self, time_source: impl TimeSource + 'static) -> Self { self.runtime_components .set_time_source(Some(time_source.into_shared())); self } + /// Configures the interceptor for the builder. pub fn interceptor(mut self, interceptor: impl Intercept + 'static) -> Self { self.runtime_components.push_interceptor(interceptor); self @@ -272,11 +287,13 @@ impl OperationBuilder { self.interceptor(ConnectionPoisoningInterceptor::new()) } + /// Configures the runtime plugin for the builder. pub fn runtime_plugin(mut self, runtime_plugin: impl RuntimePlugin + 'static) -> Self { self.runtime_plugins.push(runtime_plugin.into_shared()); self } + /// Configures the serializer for the builder. pub fn serializer( mut self, serializer: impl Fn(I2) -> Result + Send + Sync + 'static, @@ -296,6 +313,7 @@ impl OperationBuilder { } } + /// Configures the deserializer for the builder. pub fn deserializer( mut self, deserializer: impl Fn(&HttpResponse) -> Result> @@ -321,6 +339,7 @@ impl OperationBuilder { } } + /// Creates an `Operation` from the builder. pub fn build(self) -> Operation { let service_name = self.service_name.expect("service_name required"); let operation_name = self.operation_name.expect("operation_name required"); diff --git a/rust-runtime/aws-smithy-runtime/src/client/retries.rs b/rust-runtime/aws-smithy-runtime/src/client/retries.rs index b275b23528..95a901a127 100644 --- a/rust-runtime/aws-smithy-runtime/src/client/retries.rs +++ b/rust-runtime/aws-smithy-runtime/src/client/retries.rs @@ -18,11 +18,10 @@ use std::fmt; pub use client_rate_limiter::ClientRateLimiter; pub use token_bucket::TokenBucket; -#[doc(hidden)] pub use client_rate_limiter::ClientRateLimiterPartition; use std::borrow::Cow; -#[doc(hidden)] +/// Represents the retry partition, e.g. an endpoint, a region #[non_exhaustive] #[derive(Clone, Debug, Hash, PartialEq, Eq)] pub struct RetryPartition { @@ -30,6 +29,7 @@ pub struct RetryPartition { } impl RetryPartition { + /// Creates a new `RetryPartition` from the given `name`. pub fn new(name: impl Into>) -> Self { Self { name: name.into() } } diff --git a/rust-runtime/aws-smithy-runtime/src/client/retries/client_rate_limiter.rs b/rust-runtime/aws-smithy-runtime/src/client/retries/client_rate_limiter.rs index 3e010b0c60..2e1e72d3a7 100644 --- a/rust-runtime/aws-smithy-runtime/src/client/retries/client_rate_limiter.rs +++ b/rust-runtime/aws-smithy-runtime/src/client/retries/client_rate_limiter.rs @@ -14,7 +14,7 @@ use std::sync::{Arc, Mutex}; use std::time::Duration; use tracing::debug; -#[doc(hidden)] +/// Represents a partition for the rate limiter, e.g. an endpoint, a region #[non_exhaustive] #[derive(Clone, Debug, Hash, PartialEq, Eq)] pub struct ClientRateLimiterPartition { @@ -22,6 +22,7 @@ pub struct ClientRateLimiterPartition { } impl ClientRateLimiterPartition { + /// Creates a `ClientRateLimiterPartition` from the given [`RetryPartition`] pub fn new(retry_partition: RetryPartition) -> Self { Self { retry_partition } } diff --git a/rust-runtime/aws-smithy-types/src/error/metadata.rs b/rust-runtime/aws-smithy-types/src/error/metadata.rs index 6629753733..82ee85cd8d 100644 --- a/rust-runtime/aws-smithy-types/src/error/metadata.rs +++ b/rust-runtime/aws-smithy-types/src/error/metadata.rs @@ -27,7 +27,6 @@ pub trait ProvideErrorMetadata { } /// Empty error metadata -#[doc(hidden)] pub const EMPTY_ERROR_METADATA: ErrorMetadata = ErrorMetadata { code: None, message: None, From 1e5217c5e3d79f63ee160c1da811c311792fef36 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Thu, 16 Nov 2023 21:28:22 -0600 Subject: [PATCH 02/12] Remove `#[doc(hidden)]` from aws runtime crates --- .../aws-config/src/default_provider/app_name.rs | 3 +-- .../aws-config/src/default_provider/region.rs | 3 +-- aws/rust-runtime/aws-config/src/environment/app_name.rs | 8 -------- .../aws-config/src/environment/credentials.rs | 3 +-- aws/rust-runtime/aws-config/src/environment/region.rs | 3 +-- aws/rust-runtime/aws-config/src/profile/parser.rs | 1 - aws/rust-runtime/aws-inlineable/src/s3_request_id.rs | 1 - aws/rust-runtime/aws-types/src/lib.rs | 1 - aws/rust-runtime/aws-types/src/os_shim_internal.rs | 4 ++++ aws/rust-runtime/aws-types/src/sdk_config.rs | 3 +-- 10 files changed, 9 insertions(+), 21 deletions(-) diff --git a/aws/rust-runtime/aws-config/src/default_provider/app_name.rs b/aws/rust-runtime/aws-config/src/default_provider/app_name.rs index 184a1897ee..4507248a41 100644 --- a/aws/rust-runtime/aws-config/src/default_provider/app_name.rs +++ b/aws/rust-runtime/aws-config/src/default_provider/app_name.rs @@ -41,11 +41,10 @@ pub struct Builder { } impl Builder { - #[doc(hidden)] /// Configure the default chain /// /// Exposed for overriding the environment when unit-testing providers - pub fn configure(self, configuration: &ProviderConfig) -> Self { + pub(crate) fn configure(self, configuration: &ProviderConfig) -> Self { Self { provider_config: configuration.clone(), } diff --git a/aws/rust-runtime/aws-config/src/default_provider/region.rs b/aws/rust-runtime/aws-config/src/default_provider/region.rs index f7b882446e..db82b720b9 100644 --- a/aws/rust-runtime/aws-config/src/default_provider/region.rs +++ b/aws/rust-runtime/aws-config/src/default_provider/region.rs @@ -45,11 +45,10 @@ pub struct Builder { } impl Builder { - #[doc(hidden)] /// Configure the default chain /// /// Exposed for overriding the environment when unit-testing providers - pub fn configure(mut self, configuration: &ProviderConfig) -> Self { + pub(crate) fn configure(mut self, configuration: &ProviderConfig) -> Self { self.env_provider = EnvironmentVariableRegionProvider::new_with_env(configuration.env()); self.profile_file = self.profile_file.configure(configuration); self.imds = self.imds.configure(configuration); diff --git a/aws/rust-runtime/aws-config/src/environment/app_name.rs b/aws/rust-runtime/aws-config/src/environment/app_name.rs index 3abf0fdedb..d1a5924cfd 100644 --- a/aws/rust-runtime/aws-config/src/environment/app_name.rs +++ b/aws/rust-runtime/aws-config/src/environment/app_name.rs @@ -21,14 +21,6 @@ impl EnvironmentVariableAppNameProvider { Self { env: Env::real() } } - #[doc(hidden)] - /// Create an region provider from a given `Env` - /// - /// This method is used for tests that need to override environment variables. - pub fn new_with_env(env: Env) -> Self { - Self { env } - } - /// Attempts to create an `AppName` from the `AWS_SDK_UA_APP_ID` environment variable. pub fn app_name(&self) -> Option { if let Ok(name) = self.env.get("AWS_SDK_UA_APP_ID") { diff --git a/aws/rust-runtime/aws-config/src/environment/credentials.rs b/aws/rust-runtime/aws-config/src/environment/credentials.rs index fa015df41e..f7e7c0888b 100644 --- a/aws/rust-runtime/aws-config/src/environment/credentials.rs +++ b/aws/rust-runtime/aws-config/src/environment/credentials.rs @@ -58,11 +58,10 @@ impl EnvironmentVariableCredentialsProvider { Self::new_with_env(Env::real()) } - #[doc(hidden)] /// Create a new `EnvironmentVariableCredentialsProvider` with `Env` overridden /// /// This function is intended for tests that mock out the process environment. - pub fn new_with_env(env: Env) -> Self { + pub(crate) fn new_with_env(env: Env) -> Self { Self { env } } } diff --git a/aws/rust-runtime/aws-config/src/environment/region.rs b/aws/rust-runtime/aws-config/src/environment/region.rs index 48859cbe4c..2f389bb479 100644 --- a/aws/rust-runtime/aws-config/src/environment/region.rs +++ b/aws/rust-runtime/aws-config/src/environment/region.rs @@ -22,11 +22,10 @@ impl EnvironmentVariableRegionProvider { EnvironmentVariableRegionProvider { env: Env::real() } } - #[doc(hidden)] /// Create an region provider from a given `Env` /// /// This method is used for tests that need to override environment variables. - pub fn new_with_env(env: Env) -> Self { + pub(crate) fn new_with_env(env: Env) -> Self { EnvironmentVariableRegionProvider { env } } } diff --git a/aws/rust-runtime/aws-config/src/profile/parser.rs b/aws/rust-runtime/aws-config/src/profile/parser.rs index 6d6dc204a3..c2010303d2 100644 --- a/aws/rust-runtime/aws-config/src/profile/parser.rs +++ b/aws/rust-runtime/aws-config/src/profile/parser.rs @@ -237,7 +237,6 @@ impl From for ProfileFileLoadError { } } -#[doc(hidden)] #[derive(Debug, Clone)] pub struct CouldNotReadProfileFile { pub(crate) path: PathBuf, diff --git a/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs b/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs index 53b23c3cf2..ed5f4d959f 100644 --- a/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs +++ b/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs @@ -70,7 +70,6 @@ where } /// Applies the extended request ID to a generic error builder -#[doc(hidden)] pub fn apply_extended_request_id( builder: ErrorMetadataBuilder, headers: &Headers, diff --git a/aws/rust-runtime/aws-types/src/lib.rs b/aws/rust-runtime/aws-types/src/lib.rs index b3fbda83f3..d9f76ecd7c 100644 --- a/aws/rust-runtime/aws-types/src/lib.rs +++ b/aws/rust-runtime/aws-types/src/lib.rs @@ -17,7 +17,6 @@ pub mod app_name; pub mod build_metadata; pub mod endpoint_config; -#[doc(hidden)] pub mod os_shim_internal; pub mod region; pub mod request_id; diff --git a/aws/rust-runtime/aws-types/src/os_shim_internal.rs b/aws/rust-runtime/aws-types/src/os_shim_internal.rs index 53b26706f7..ad806bd6f2 100644 --- a/aws/rust-runtime/aws-types/src/os_shim_internal.rs +++ b/aws/rust-runtime/aws-types/src/os_shim_internal.rs @@ -45,14 +45,17 @@ impl Default for Fs { } impl Fs { + /// Create `Fs` representing a real file system. pub fn real() -> Self { Fs(fs::Inner::Real) } + /// Create `Fs` from a map of `OsString` to `Vec`. pub fn from_raw_map(fs: HashMap>) -> Self { Fs(fs::Inner::Fake(Arc::new(Fake::MapFs(Mutex::new(fs))))) } + /// Create `Fs` from a map of `String` to `Vec`. pub fn from_map(data: HashMap>>) -> Self { let fs = data .into_iter() @@ -224,6 +227,7 @@ impl Default for Env { } impl Env { + /// Retrieve a value for the given `k` and return `VarError` is that key is not present. pub fn get(&self, k: &str) -> Result { use env::Inner; match &self.0 { diff --git a/aws/rust-runtime/aws-types/src/sdk_config.rs b/aws/rust-runtime/aws-types/src/sdk_config.rs index 6ea10806f1..9d7910f3c0 100644 --- a/aws/rust-runtime/aws-types/src/sdk_config.rs +++ b/aws/rust-runtime/aws-types/src/sdk_config.rs @@ -25,9 +25,9 @@ use aws_smithy_runtime_api::shared::IntoShared; pub use aws_smithy_types::retry::RetryConfig; pub use aws_smithy_types::timeout::TimeoutConfig; -#[doc(hidden)] /// Unified docstrings to keep crates in sync. Not intended for public use pub mod unified_docs { + /// A macro that generates docs for selected fields of `SdkConfig`. #[macro_export] macro_rules! docs_for { (use_fips) => { @@ -592,7 +592,6 @@ impl SdkConfig { self.timeout_config.as_ref() } - #[doc(hidden)] /// Configured sleep implementation pub fn sleep_impl(&self) -> Option { self.sleep_impl.clone() From 3bb1d122ecf686e2faf3dbef66eac6950bf3e658 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Thu, 16 Nov 2023 21:29:00 -0600 Subject: [PATCH 03/12] Remove `#[doc(hidden)]` from codegen client --- .../smithy/customizations/ResiliencyConfigCustomization.kt | 3 --- .../codegen/client/smithy/generators/OperationGenerator.kt | 4 ++-- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt b/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt index a945ae2fc1..5a8f04e177 100644 --- a/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt +++ b/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt @@ -65,7 +65,6 @@ class ResiliencyConfigCustomization(codegenContext: ClientCodegenContext) : Conf self.config.load::<#{TimeoutConfig}>() } - ##[doc(hidden)] /// Returns a reference to the retry partition contained in this config, if any. /// /// WARNING: This method is unstable and may be removed at any time. Do not rely on this @@ -248,7 +247,6 @@ class ResiliencyConfigCustomization(codegenContext: ClientCodegenContext) : Conf *codegenScope, ) - Attribute.DocHidden.render(this) rustTemplate( """ /// Set the partition for retry-related state. When clients share a retry partition, they will @@ -262,7 +260,6 @@ class ResiliencyConfigCustomization(codegenContext: ClientCodegenContext) : Conf *codegenScope, ) - Attribute.DocHidden.render(this) rustTemplate( """ /// Set the partition for retry-related state. When clients share a retry partition, they will diff --git a/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/OperationGenerator.kt b/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/OperationGenerator.kt index 842a427f5e..f96534ed9d 100644 --- a/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/OperationGenerator.kt +++ b/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/OperationGenerator.kt @@ -16,6 +16,7 @@ import software.amazon.smithy.rust.codegen.client.smithy.protocols.ClientHttpBou import software.amazon.smithy.rust.codegen.core.rustlang.Attribute import software.amazon.smithy.rust.codegen.core.rustlang.Attribute.Companion.derive import software.amazon.smithy.rust.codegen.core.rustlang.RustWriter +import software.amazon.smithy.rust.codegen.core.rustlang.docs import software.amazon.smithy.rust.codegen.core.rustlang.implBlock import software.amazon.smithy.rust.codegen.core.rustlang.isNotEmpty import software.amazon.smithy.rust.codegen.core.rustlang.rust @@ -77,10 +78,9 @@ open class OperationGenerator( ) Attribute(derive(RuntimeType.Clone, RuntimeType.Default, RuntimeType.Debug)).render(operationWriter) Attribute.NonExhaustive.render(operationWriter) - Attribute.DocHidden.render(operationWriter) operationWriter.rust("pub struct $operationName;") operationWriter.implBlock(symbolProvider.toSymbol(operationShape)) { - Attribute.DocHidden.render(operationWriter) + docs("Creates a new `$operationName`") rustBlock("pub fn new() -> Self") { rust("Self") } From 54a412a1e4a3f05eb309832bfb76bfb6285a0012 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Thu, 16 Nov 2023 22:01:15 -0600 Subject: [PATCH 04/12] Add error metadata builder to allowed external types in `aws-inlineable` --- aws/rust-runtime/aws-inlineable/external-types.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/aws/rust-runtime/aws-inlineable/external-types.toml b/aws/rust-runtime/aws-inlineable/external-types.toml index 62904a6e4c..fb91790f9d 100644 --- a/aws/rust-runtime/aws-inlineable/external-types.toml +++ b/aws/rust-runtime/aws-inlineable/external-types.toml @@ -2,6 +2,7 @@ allowed_external_types = [ "aws_credential_types::provider::ProvideCredentials", "aws_smithy_http::*", "aws_smithy_runtime_api::*", + "aws_smithy_types::error::metadata::Builder", "http::error::Error", "http::header::map::HeaderMap", From 0c30d9747e14c1ff67415730668742d6c6d964de Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Thu, 16 Nov 2023 22:05:57 -0600 Subject: [PATCH 05/12] Add `RetryPartition` to allowed external types in sdk crates --- aws/sdk/sdk-external-types.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/aws/sdk/sdk-external-types.toml b/aws/sdk/sdk-external-types.toml index 0fa9bbc3a2..2de1ff7c41 100644 --- a/aws/sdk/sdk-external-types.toml +++ b/aws/sdk/sdk-external-types.toml @@ -14,6 +14,7 @@ allowed_external_types = [ "aws_smithy_eventstream::*", "aws_smithy_runtime::client::identity::cache::IdentityCache", + "aws_smithy_runtime::client::retries::RetryPartition", "aws_runtime::invocation_id::SharedInvocationIdGenerator", "aws_runtime::invocation_id::InvocationIdGenerator", From bd33526fc674086b7b78c0961e469024cdf97656 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Thu, 16 Nov 2023 22:08:38 -0600 Subject: [PATCH 06/12] Remove unused import in `ResiliencyConfigCustomization.kt` --- .../smithy/customizations/ResiliencyConfigCustomization.kt | 1 - 1 file changed, 1 deletion(-) diff --git a/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt b/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt index 5a8f04e177..0f64fa0ccf 100644 --- a/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt +++ b/codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt @@ -10,7 +10,6 @@ import software.amazon.smithy.rust.codegen.client.smithy.ClientRustModule import software.amazon.smithy.rust.codegen.client.smithy.configReexport import software.amazon.smithy.rust.codegen.client.smithy.generators.config.ConfigCustomization import software.amazon.smithy.rust.codegen.client.smithy.generators.config.ServiceConfig -import software.amazon.smithy.rust.codegen.core.rustlang.Attribute import software.amazon.smithy.rust.codegen.core.rustlang.rustTemplate import software.amazon.smithy.rust.codegen.core.rustlang.writable import software.amazon.smithy.rust.codegen.core.smithy.RuntimeType From c21af072c62f27ab9766c82ce0aa8412a69cf51a Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Thu, 16 Nov 2023 22:26:55 -0600 Subject: [PATCH 07/12] Update CHANGELOG.next.toml --- CHANGELOG.next.toml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CHANGELOG.next.toml b/CHANGELOG.next.toml index a99b8c59a8..21a899ac7d 100644 --- a/CHANGELOG.next.toml +++ b/CHANGELOG.next.toml @@ -28,3 +28,15 @@ message = "The `AssumeRoleBuilder::policy_arns` now accepts strings instead of a references = ["smithy-rs#3205"] meta = { "breaking" = true, "tada" = false, "bug" = false } author = "rcoh" + +[[aws-sdk-rust]] +message = "Types/functions that were previously `#[doc(hidden)]` in `aws-config`, `aws-inlineable`, `aws-types`, and the SDK crates are now visible. For those that are not intended to be used directly, they are called out in their docs as such." +references = ["smithy-rs#3225"] +meta = { "breaking" = false, "tada" = false, "bug" = false } +author = "ysaito1001" + +[[smithy-rs]] +message = "Types/functions that were previously `#[doc(hidden)]` in `aws-smithy-async`, `aws-smithy-runtime-api`, `aws-smithy-runtime`, `aws-smithy-types`, and the SDK crates are now visible. For those that are not intended to be used directly, they are called out in their docs as such." +references = ["smithy-rs#3225"] +meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "client" } +author = "ysaito1001" From 5ffda1ff05e343524035bcf3529528eb0fe94ff0 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Thu, 16 Nov 2023 22:30:21 -0600 Subject: [PATCH 08/12] Add doc for `CouldNotReadProfileFile` --- aws/rust-runtime/aws-config/src/profile/parser.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/aws/rust-runtime/aws-config/src/profile/parser.rs b/aws/rust-runtime/aws-config/src/profile/parser.rs index c2010303d2..ef291e264b 100644 --- a/aws/rust-runtime/aws-config/src/profile/parser.rs +++ b/aws/rust-runtime/aws-config/src/profile/parser.rs @@ -237,6 +237,7 @@ impl From for ProfileFileLoadError { } } +/// An error encountered while reading the AWS config file #[derive(Debug, Clone)] pub struct CouldNotReadProfileFile { pub(crate) path: PathBuf, From 90ff3605f5548fd51b6aaffec42533677cdea011 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Thu, 16 Nov 2023 22:56:42 -0600 Subject: [PATCH 09/12] Bump pull request number in CHANGELOG.next.toml --- CHANGELOG.next.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.next.toml b/CHANGELOG.next.toml index 471644df9f..b51aceb0da 100644 --- a/CHANGELOG.next.toml +++ b/CHANGELOG.next.toml @@ -19,12 +19,12 @@ author = "milesziemer" [[aws-sdk-rust]] message = "Types/functions that were previously `#[doc(hidden)]` in `aws-config`, `aws-inlineable`, `aws-types`, and the SDK crates are now visible. For those that are not intended to be used directly, they are called out in their docs as such." -references = ["smithy-rs#3225"] +references = ["smithy-rs#3226"] meta = { "breaking" = false, "tada" = false, "bug" = false } author = "ysaito1001" [[smithy-rs]] message = "Types/functions that were previously `#[doc(hidden)]` in `aws-smithy-async`, `aws-smithy-runtime-api`, `aws-smithy-runtime`, `aws-smithy-types`, and the SDK crates are now visible. For those that are not intended to be used directly, they are called out in their docs as such." -references = ["smithy-rs#3225"] +references = ["smithy-rs#3226"] meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "client" } author = "ysaito1001" From c6433ca7f2c351cf27a5c2570a32db0538e363e8 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Fri, 17 Nov 2023 10:51:02 -0600 Subject: [PATCH 10/12] `apply_extended_request_id` can stay as `pub(crate)` This commit addresses https://github.com/smithy-lang/smithy-rs/pull/3226#discussion_r1397582812 --- aws/rust-runtime/aws-inlineable/external-types.toml | 1 - aws/rust-runtime/aws-inlineable/src/s3_request_id.rs | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/aws/rust-runtime/aws-inlineable/external-types.toml b/aws/rust-runtime/aws-inlineable/external-types.toml index fb91790f9d..62904a6e4c 100644 --- a/aws/rust-runtime/aws-inlineable/external-types.toml +++ b/aws/rust-runtime/aws-inlineable/external-types.toml @@ -2,7 +2,6 @@ allowed_external_types = [ "aws_credential_types::provider::ProvideCredentials", "aws_smithy_http::*", "aws_smithy_runtime_api::*", - "aws_smithy_types::error::metadata::Builder", "http::error::Error", "http::header::map::HeaderMap", diff --git a/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs b/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs index ed5f4d959f..b38e3ec3d6 100644 --- a/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs +++ b/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs @@ -70,7 +70,7 @@ where } /// Applies the extended request ID to a generic error builder -pub fn apply_extended_request_id( +pub(crate) fn apply_extended_request_id( builder: ErrorMetadataBuilder, headers: &Headers, ) -> ErrorMetadataBuilder { From 55f1c75559c80281eef9cac17db3f54f253d7cc7 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Fri, 17 Nov 2023 11:31:46 -0600 Subject: [PATCH 11/12] Add disclaimer to docs for `InterceptorContext` methods This commit addresses https://github.com/smithy-lang/smithy-rs/pull/3226#discussion_r1397583873 --- .../src/client/interceptors/context.rs | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/rust-runtime/aws-smithy-runtime-api/src/client/interceptors/context.rs b/rust-runtime/aws-smithy-runtime-api/src/client/interceptors/context.rs index 31793243b2..c7054c11c7 100644 --- a/rust-runtime/aws-smithy-runtime-api/src/client/interceptors/context.rs +++ b/rust-runtime/aws-smithy-runtime-api/src/client/interceptors/context.rs @@ -147,73 +147,101 @@ impl InterceptorContext { impl InterceptorContext { /// Retrieve the input for the operation being invoked. + /// + /// Note: This method is intended for internal use only. pub fn input(&self) -> Option<&I> { self.input.as_ref() } /// Retrieve the input for the operation being invoked. + /// + /// Note: This method is intended for internal use only. pub fn input_mut(&mut self) -> Option<&mut I> { self.input.as_mut() } /// Takes ownership of the input. + /// + /// Note: This method is intended for internal use only. pub fn take_input(&mut self) -> Option { self.input.take() } /// Set the request for the operation being invoked. + /// + /// Note: This method is intended for internal use only. pub fn set_request(&mut self, request: Request) { self.request = Some(request); } /// Retrieve the transmittable request for the operation being invoked. /// This will only be available once request marshalling has completed. + /// + /// Note: This method is intended for internal use only. pub fn request(&self) -> Option<&Request> { self.request.as_ref() } /// Retrieve the transmittable request for the operation being invoked. /// This will only be available once request marshalling has completed. + /// + /// Note: This method is intended for internal use only. pub fn request_mut(&mut self) -> Option<&mut Request> { self.request.as_mut() } /// Takes ownership of the request. + /// + /// Note: This method is intended for internal use only. pub fn take_request(&mut self) -> Option { self.request.take() } /// Set the response for the operation being invoked. + /// + /// Note: This method is intended for internal use only. pub fn set_response(&mut self, response: Response) { self.response = Some(response); } /// Returns the response. + /// + /// Note: This method is intended for internal use only. pub fn response(&self) -> Option<&Response> { self.response.as_ref() } /// Returns a mutable reference to the response. + /// + /// Note: This method is intended for internal use only. pub fn response_mut(&mut self) -> Option<&mut Response> { self.response.as_mut() } /// Set the output or error for the operation being invoked. + /// + /// Note: This method is intended for internal use only. pub fn set_output_or_error(&mut self, output: Result>) { self.output_or_error = Some(output); } /// Returns the deserialized output or error. + /// + /// Note: This method is intended for internal use only. pub fn output_or_error(&self) -> Option>> { self.output_or_error.as_ref().map(Result::as_ref) } /// Returns the mutable reference to the deserialized output or error. + /// + /// Note: This method is intended for internal use only. pub fn output_or_error_mut(&mut self) -> Option<&mut Result>> { self.output_or_error.as_mut() } /// Return `true` if this context's `output_or_error` is an error. Otherwise, return `false`. + /// + /// Note: This method is intended for internal use only. pub fn is_failed(&self) -> bool { self.output_or_error .as_ref() @@ -222,6 +250,8 @@ impl InterceptorContext { } /// Advance to the Serialization phase. + /// + /// Note: This method is intended for internal use only. pub fn enter_serialization_phase(&mut self) { debug!("entering \'serialization\' phase"); debug_assert!( @@ -232,6 +262,8 @@ impl InterceptorContext { } /// Advance to the BeforeTransmit phase. + /// + /// Note: This method is intended for internal use only. pub fn enter_before_transmit_phase(&mut self) { debug!("entering \'before transmit\' phase"); debug_assert!( @@ -251,6 +283,8 @@ impl InterceptorContext { } /// Advance to the Transmit phase. + /// + /// Note: This method is intended for internal use only. pub fn enter_transmit_phase(&mut self) { debug!("entering \'transmit\' phase"); debug_assert!( @@ -261,6 +295,8 @@ impl InterceptorContext { } /// Advance to the BeforeDeserialization phase. + /// + /// Note: This method is intended for internal use only. pub fn enter_before_deserialization_phase(&mut self) { debug!("entering \'before deserialization\' phase"); debug_assert!( @@ -279,6 +315,8 @@ impl InterceptorContext { } /// Advance to the Deserialization phase. + /// + /// Note: This method is intended for internal use only. pub fn enter_deserialization_phase(&mut self) { debug!("entering \'deserialization\' phase"); debug_assert!( @@ -289,6 +327,8 @@ impl InterceptorContext { } /// Advance to the AfterDeserialization phase. + /// + /// Note: This method is intended for internal use only. pub fn enter_after_deserialization_phase(&mut self) { debug!("entering \'after deserialization\' phase"); debug_assert!( @@ -303,6 +343,8 @@ impl InterceptorContext { } /// Set the request checkpoint. This should only be called once, right before entering the retry loop. + /// + /// Note: This method is intended for internal use only. pub fn save_checkpoint(&mut self) { trace!("saving request checkpoint..."); self.request_checkpoint = self.request().and_then(|r| r.try_clone()); @@ -313,6 +355,8 @@ impl InterceptorContext { } /// Returns false if rewinding isn't possible + /// + /// Note: This method is intended for internal use only. pub fn rewind(&mut self, _cfg: &mut ConfigBag) -> RewindResult { // If request_checkpoint was never set, but we've already made one attempt, // then this is not a retryable request @@ -343,6 +387,8 @@ where E: Debug, { /// Decomposes the context into its constituent parts. + /// + /// Note: This method is intended for internal use only. #[allow(clippy::type_complexity)] pub fn into_parts( self, @@ -361,6 +407,8 @@ where } /// Convert this context into the final operation result that is returned in client's the public API. + /// + /// Note: This method is intended for internal use only. pub fn finalize(self) -> Result> { let Self { output_or_error, @@ -375,6 +423,8 @@ where /// Mark this context as failed due to errors during the operation. Any errors already contained /// by the context will be replaced by the given error. + /// + /// Note: This method is intended for internal use only. pub fn fail(&mut self, error: OrchestratorError) { if !self.is_failed() { trace!( @@ -389,6 +439,8 @@ where } /// The result of attempting to rewind a request. +/// +/// Note: This is intended for internal use only. #[non_exhaustive] #[derive(Debug, PartialEq, Eq, Clone, Copy)] pub enum RewindResult { From 3e9bcc6313907fc8100fcddbb8436f2e901d85f4 Mon Sep 17 00:00:00 2001 From: ysaito1001 Date: Fri, 17 Nov 2023 12:44:24 -0600 Subject: [PATCH 12/12] Inline `builder!` and remove the `macros` module from runtime-api This commit addresses https://github.com/smithy-lang/smithy-rs/pull/3226#discussion_r1397585773 --- .../aws-smithy-runtime-api/src/lib.rs | 3 - .../aws-smithy-runtime-api/src/macros.rs | 165 ------------------ .../src/client/retries/client_rate_limiter.rs | 153 ++++++++++++++-- 3 files changed, 139 insertions(+), 182 deletions(-) delete mode 100644 rust-runtime/aws-smithy-runtime-api/src/macros.rs diff --git a/rust-runtime/aws-smithy-runtime-api/src/lib.rs b/rust-runtime/aws-smithy-runtime-api/src/lib.rs index 2741caf8a2..be0ca84d61 100644 --- a/rust-runtime/aws-smithy-runtime-api/src/lib.rs +++ b/rust-runtime/aws-smithy-runtime-api/src/lib.rs @@ -33,7 +33,4 @@ pub mod client; pub mod http; -/// Builder macros. Not intended to be used outside of the aws-smithy-runtime crates. -pub mod macros; - pub mod shared; diff --git a/rust-runtime/aws-smithy-runtime-api/src/macros.rs b/rust-runtime/aws-smithy-runtime-api/src/macros.rs deleted file mode 100644 index 09efd0a74c..0000000000 --- a/rust-runtime/aws-smithy-runtime-api/src/macros.rs +++ /dev/null @@ -1,165 +0,0 @@ -/* - * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. - * SPDX-License-Identifier: Apache-2.0 - */ - -//! Various utility macros to aid runtime crate writers. - -/// Define a new builder struct, along with a method to create it, and setters. -/// -/// ## Examples -/// -/// The builder macro takes a list of field definitions, each with four elements: -/// ```txt -/// set_optional_field, optional_field, String, "An optional field which may or may not be set when `.build()` is called.", -/// ^ The setter name, ^ The field name, ^ The type, ^ The documentation for the field and setter methods. -/// ``` -/// -/// The following example creates a new builder struct, along with a method to create it, and setters -/// for a struct `MyConfig` with three fields: -/// -/// ``` -/// use std::collections::HashMap; -/// use std::sync::{Arc, Mutex}; -/// use aws_smithy_runtime_api::{builder, builder_methods, builder_struct}; -/// -/// struct MyConfig { -/// optional_field: Option, -/// optional_field_with_a_default: f64, -/// required_field_with_no_default: Arc>>, -/// } -/// -/// impl MyConfig { -/// pub fn builder() -> Builder { -/// Builder::new() -/// } -/// } -/// -/// builder!( -/// set_optional_field, optional_field, String, "An optional field which may or may not be set when `.build()` is called.", -/// set_optional_field_with_a_default, optional_field_with_a_default, f64, "An optional field that will default to `f64::MAX` if it's unset when `.build()` is called.", -/// set_required_field_with_no_default, required_field_with_no_default, HashMap, "A required field that will cause the builder to panic if it's unset when `.build()` is called." -/// ); -/// -/// impl Builder { -/// fn build(self) -> MyConfig { -/// MyConfig { -/// optional_field: self.optional_field, -/// optional_field_with_a_default: self.optional_field_with_a_default.unwrap_or(f64::MAX), -/// required_field_with_no_default: Arc::new(Mutex::new( -/// self.required_field_with_no_default.expect("'required_field_with_no_default' is required") -/// )), -/// } -/// } -/// } -/// ``` -/// -/// In this example, the result of macro expansion would look like this: -/// -/// ``` -/// # use std::collections::HashMap; -/// # use std::sync::{Arc, Mutex}; -/// #[derive(Clone, Debug, Default)] -/// pub struct Builder { -/// #[doc = "An optional field which may or may not be set when `.build()` is called."] -/// optional_field: Option, -/// #[doc = "An optional field that will default to `f64::MAX` if it's unset when `.build()` is called."] -/// optional_field_with_a_default: Option, -/// #[doc = "A required field that will cause the builder to panic if it's unset when `.build()` is called."] -/// required_field_with_no_default: Option>, -/// } -/// -/// impl Builder { -/// pub fn new() -> Self { -/// Builder::default() -/// } -/// -/// #[doc = "An optional field which may or may not be set when `.build()` is called."] -/// pub fn set_optional_field(&mut self, optional_field: Option) -> &mut Self { -/// self.optional_field = optional_field; -/// self -/// } -/// -/// #[doc = "An optional field which may or may not be set when `.build()` is called."] -/// pub fn optional_field(mut self, optional_field: String) -> Self { -/// self.optional_field = Some(optional_field); -/// self -/// } -/// -/// #[doc = "An optional field that will default to `f64::MAX` if it's unset when `.build()` is called."] -/// pub fn set_optional_field_with_a_default(&mut self, optional_field_with_a_default: Option) -> &mut Self { -/// self.optional_field_with_a_default = optional_field_with_a_default; -/// self -/// } -/// -/// #[doc = "An optional field that will default to `f64::MAX` if it's unset when `.build()` is called."] -/// pub fn optional_field_with_a_default(mut self, optional_field_with_a_default: f64) -> Self { -/// self.optional_field_with_a_default = Some(optional_field_with_a_default); -/// self -/// } -/// -/// #[doc = "A required field that will cause the builder to panic if it's unset when `.build()` is called."] -/// pub fn set_required_field_with_no_default(&mut self, required_field_with_no_default: Option>) -> &mut Self { -/// self.required_field_with_no_default = required_field_with_no_default; -/// self -/// } -/// -/// #[doc = "A required field that will cause the builder to panic if it's unset when `.build()` is called."] -/// pub fn required_field_with_no_default(mut self, required_field_with_no_default: HashMap) -> Self { -/// self.required_field_with_no_default = Some(required_field_with_no_default); -/// self -/// } -/// } -/// ``` -#[macro_export] -macro_rules! builder { - ($($tt:tt)+) => { - builder_struct!($($tt)+); - - impl Builder { - pub fn new() -> Self { - Builder::default() - } - - builder_methods!($($tt)+); - } - } -} - -/// Define a new builder struct, its fields, and their docs. This macro is intended to be called -/// by the `builder!` macro and should not be called directly. -#[macro_export] -macro_rules! builder_struct { - ($($_setter_name:ident, $field_name:ident, $ty:ty, $doc:literal $(,)?)+) => { - #[derive(Clone, Debug, Default)] - pub struct Builder { - $( - #[doc = $doc] - $field_name: Option<$ty>, - )+ - } - } -} - -/// Define setter methods for a builder struct. Must be called from within an `impl` block. This -/// macro is intended to be called by the `builder!` macro and should not be called directly. -#[macro_export] -macro_rules! builder_methods { - ($fn_name:ident, $arg_name:ident, $ty:ty, $doc:literal, $($tail:tt)+) => { - builder_methods!($fn_name, $arg_name, $ty, $doc); - builder_methods!($($tail)+); - }; - ($fn_name:ident, $arg_name:ident, $ty:ty, $doc:literal) => { - #[doc = $doc] - pub fn $fn_name(&mut self, $arg_name: Option<$ty>) -> &mut Self { - self.$arg_name = $arg_name; - self - } - - #[doc = $doc] - pub fn $arg_name(mut self, $arg_name: $ty) -> Self { - self.$arg_name = Some($arg_name); - self - } - }; -} diff --git a/rust-runtime/aws-smithy-runtime/src/client/retries/client_rate_limiter.rs b/rust-runtime/aws-smithy-runtime/src/client/retries/client_rate_limiter.rs index 2e1e72d3a7..80efa6a81d 100644 --- a/rust-runtime/aws-smithy-runtime/src/client/retries/client_rate_limiter.rs +++ b/rust-runtime/aws-smithy-runtime/src/client/retries/client_rate_limiter.rs @@ -9,7 +9,6 @@ #![allow(dead_code)] use crate::client::retries::RetryPartition; -use aws_smithy_runtime_api::{builder, builder_methods, builder_struct}; use std::sync::{Arc, Mutex}; use std::time::Duration; use tracing::debug; @@ -79,7 +78,7 @@ pub(crate) enum RequestReason { } impl ClientRateLimiter { - /// Creates a new [`ClientRateLimiter`]. + /// Creates a new `ClientRateLimiter` pub fn new(seconds_since_unix_epoch: f64) -> Self { Self::builder() .tokens_retrieved_per_second(MIN_FILL_RATE) @@ -232,20 +231,146 @@ fn cubic_throttle(rate_to_use: f64) -> f64 { rate_to_use * BETA } -builder!( - set_token_refill_rate, token_refill_rate, f64, "The rate at which token are replenished.", - set_maximum_bucket_capacity, maximum_bucket_capacity, f64, "The maximum capacity allowed in the token bucket.", - set_current_bucket_capacity, current_bucket_capacity, f64, "The current capacity of the token bucket. The minimum this can be is 1.0", - set_time_of_last_refill, time_of_last_refill, f64, "The last time the token bucket was refilled.", - set_tokens_retrieved_per_second, tokens_retrieved_per_second, f64, "The smoothed rate which tokens are being retrieved.", - set_previous_time_bucket, previous_time_bucket, f64, "The last half second time bucket used.", - set_request_count, request_count, u64, "The number of requests seen within the current time bucket.", - set_enable_throttling, enable_throttling, bool, "Boolean indicating if the token bucket is enabled. The token bucket is initially disabled. When a throttling error is encountered it is enabled.", - set_tokens_retrieved_per_second_at_time_of_last_throttle, tokens_retrieved_per_second_at_time_of_last_throttle, f64, "The maximum rate when the client was last throttled.", - set_time_of_last_throttle, time_of_last_throttle, f64, "The last time when the client was throttled." -); +#[derive(Clone, Debug, Default)] +struct Builder { + ///The rate at which token are replenished. + token_refill_rate: Option, + ///The maximum capacity allowed in the token bucket. + maximum_bucket_capacity: Option, + ///The current capacity of the token bucket. The minimum this can be is 1.0 + current_bucket_capacity: Option, + ///The last time the token bucket was refilled. + time_of_last_refill: Option, + ///The smoothed rate which tokens are being retrieved. + tokens_retrieved_per_second: Option, + ///The last half second time bucket used. + previous_time_bucket: Option, + ///The number of requests seen within the current time bucket. + request_count: Option, + ///Boolean indicating if the token bucket is enabled. The token bucket is initially disabled. When a throttling error is encountered it is enabled. + enable_throttling: Option, + ///The maximum rate when the client was last throttled. + tokens_retrieved_per_second_at_time_of_last_throttle: Option, + ///The last time when the client was throttled. + time_of_last_throttle: Option, +} impl Builder { + fn new() -> Self { + Builder::default() + } + ///The rate at which token are replenished. + fn set_token_refill_rate(&mut self, token_refill_rate: Option) -> &mut Self { + self.token_refill_rate = token_refill_rate; + self + } + ///The rate at which token are replenished. + fn token_refill_rate(mut self, token_refill_rate: f64) -> Self { + self.token_refill_rate = Some(token_refill_rate); + self + } + ///The maximum capacity allowed in the token bucket. + fn set_maximum_bucket_capacity(&mut self, maximum_bucket_capacity: Option) -> &mut Self { + self.maximum_bucket_capacity = maximum_bucket_capacity; + self + } + ///The maximum capacity allowed in the token bucket. + fn maximum_bucket_capacity(mut self, maximum_bucket_capacity: f64) -> Self { + self.maximum_bucket_capacity = Some(maximum_bucket_capacity); + self + } + ///The current capacity of the token bucket. The minimum this can be is 1.0 + fn set_current_bucket_capacity(&mut self, current_bucket_capacity: Option) -> &mut Self { + self.current_bucket_capacity = current_bucket_capacity; + self + } + ///The current capacity of the token bucket. The minimum this can be is 1.0 + fn current_bucket_capacity(mut self, current_bucket_capacity: f64) -> Self { + self.current_bucket_capacity = Some(current_bucket_capacity); + self + } + ///The last time the token bucket was refilled. + fn set_time_of_last_refill(&mut self, time_of_last_refill: Option) -> &mut Self { + self.time_of_last_refill = time_of_last_refill; + self + } + ///The last time the token bucket was refilled. + fn time_of_last_refill(mut self, time_of_last_refill: f64) -> Self { + self.time_of_last_refill = Some(time_of_last_refill); + self + } + ///The smoothed rate which tokens are being retrieved. + fn set_tokens_retrieved_per_second( + &mut self, + tokens_retrieved_per_second: Option, + ) -> &mut Self { + self.tokens_retrieved_per_second = tokens_retrieved_per_second; + self + } + ///The smoothed rate which tokens are being retrieved. + fn tokens_retrieved_per_second(mut self, tokens_retrieved_per_second: f64) -> Self { + self.tokens_retrieved_per_second = Some(tokens_retrieved_per_second); + self + } + ///The last half second time bucket used. + fn set_previous_time_bucket(&mut self, previous_time_bucket: Option) -> &mut Self { + self.previous_time_bucket = previous_time_bucket; + self + } + ///The last half second time bucket used. + fn previous_time_bucket(mut self, previous_time_bucket: f64) -> Self { + self.previous_time_bucket = Some(previous_time_bucket); + self + } + ///The number of requests seen within the current time bucket. + fn set_request_count(&mut self, request_count: Option) -> &mut Self { + self.request_count = request_count; + self + } + ///The number of requests seen within the current time bucket. + fn request_count(mut self, request_count: u64) -> Self { + self.request_count = Some(request_count); + self + } + ///Boolean indicating if the token bucket is enabled. The token bucket is initially disabled. When a throttling error is encountered it is enabled. + fn set_enable_throttling(&mut self, enable_throttling: Option) -> &mut Self { + self.enable_throttling = enable_throttling; + self + } + ///Boolean indicating if the token bucket is enabled. The token bucket is initially disabled. When a throttling error is encountered it is enabled. + fn enable_throttling(mut self, enable_throttling: bool) -> Self { + self.enable_throttling = Some(enable_throttling); + self + } + ///The maximum rate when the client was last throttled. + fn set_tokens_retrieved_per_second_at_time_of_last_throttle( + &mut self, + tokens_retrieved_per_second_at_time_of_last_throttle: Option, + ) -> &mut Self { + self.tokens_retrieved_per_second_at_time_of_last_throttle = + tokens_retrieved_per_second_at_time_of_last_throttle; + self + } + ///The maximum rate when the client was last throttled. + fn tokens_retrieved_per_second_at_time_of_last_throttle( + mut self, + tokens_retrieved_per_second_at_time_of_last_throttle: f64, + ) -> Self { + self.tokens_retrieved_per_second_at_time_of_last_throttle = + Some(tokens_retrieved_per_second_at_time_of_last_throttle); + self + } + ///The last time when the client was throttled. + fn set_time_of_last_throttle(&mut self, time_of_last_throttle: Option) -> &mut Self { + self.time_of_last_throttle = time_of_last_throttle; + self + } + ///The last time when the client was throttled. + fn time_of_last_throttle(mut self, time_of_last_throttle: f64) -> Self { + self.time_of_last_throttle = Some(time_of_last_throttle); + self + } + fn build(self) -> ClientRateLimiter { ClientRateLimiter { inner: Arc::new(Mutex::new(Inner {