aws_runtime/user_agent/
interceptor.rs

1/*
2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 */
5
6use std::borrow::Cow;
7use std::fmt;
8
9use http_02x::header::{HeaderName, HeaderValue, InvalidHeaderValue, USER_AGENT};
10
11use aws_credential_types::credential_feature::AwsCredentialFeature;
12use aws_smithy_runtime::client::sdk_feature::SmithySdkFeature;
13use aws_smithy_runtime_api::box_error::BoxError;
14use aws_smithy_runtime_api::client::http::HttpClient;
15use aws_smithy_runtime_api::client::interceptors::context::{
16    BeforeTransmitInterceptorContextMut, BeforeTransmitInterceptorContextRef,
17};
18use aws_smithy_runtime_api::client::interceptors::Intercept;
19use aws_smithy_runtime_api::client::runtime_components::RuntimeComponents;
20use aws_smithy_types::config_bag::ConfigBag;
21use aws_types::app_name::AppName;
22use aws_types::os_shim_internal::Env;
23
24use crate::sdk_feature::AwsSdkFeature;
25use crate::user_agent::metrics::ProvideBusinessMetric;
26use crate::user_agent::{AdditionalMetadata, ApiMetadata, AwsUserAgent, InvalidMetadataValue};
27
28macro_rules! add_metrics_unique {
29    ($features:expr, $ua:expr, $added:expr) => {
30        for feature in $features {
31            if let Some(m) = feature.provide_business_metric() {
32                if !$added.contains(&m) {
33                    $added.insert(m.clone());
34                    $ua.add_business_metric(m);
35                }
36            }
37        }
38    };
39}
40
41macro_rules! add_metrics_unique_reverse {
42    ($features:expr, $ua:expr, $added:expr) => {
43        let mut unique_metrics = Vec::new();
44        for feature in $features {
45            if let Some(m) = feature.provide_business_metric() {
46                if !$added.contains(&m) {
47                    $added.insert(m.clone());
48                    unique_metrics.push(m);
49                }
50            }
51        }
52        for m in unique_metrics.into_iter().rev() {
53            $ua.add_business_metric(m);
54        }
55    };
56}
57
58#[allow(clippy::declare_interior_mutable_const)] // we will never mutate this
59const X_AMZ_USER_AGENT: HeaderName = HeaderName::from_static("x-amz-user-agent");
60
61#[derive(Debug)]
62enum UserAgentInterceptorError {
63    MissingApiMetadata,
64    InvalidHeaderValue(InvalidHeaderValue),
65    InvalidMetadataValue(InvalidMetadataValue),
66}
67
68impl std::error::Error for UserAgentInterceptorError {
69    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
70        match self {
71            Self::InvalidHeaderValue(source) => Some(source),
72            Self::InvalidMetadataValue(source) => Some(source),
73            Self::MissingApiMetadata => None,
74        }
75    }
76}
77
78impl fmt::Display for UserAgentInterceptorError {
79    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
80        f.write_str(match self {
81            Self::InvalidHeaderValue(_) => "AwsUserAgent generated an invalid HTTP header value. This is a bug. Please file an issue.",
82            Self::InvalidMetadataValue(_) => "AwsUserAgent generated an invalid metadata value. This is a bug. Please file an issue.",
83            Self::MissingApiMetadata => "The UserAgentInterceptor requires ApiMetadata to be set before the request is made. This is a bug. Please file an issue.",
84        })
85    }
86}
87
88impl From<InvalidHeaderValue> for UserAgentInterceptorError {
89    fn from(err: InvalidHeaderValue) -> Self {
90        UserAgentInterceptorError::InvalidHeaderValue(err)
91    }
92}
93
94impl From<InvalidMetadataValue> for UserAgentInterceptorError {
95    fn from(err: InvalidMetadataValue) -> Self {
96        UserAgentInterceptorError::InvalidMetadataValue(err)
97    }
98}
99
100/// Generates and attaches the AWS SDK's user agent to a HTTP request
101#[non_exhaustive]
102#[derive(Debug, Default)]
103pub struct UserAgentInterceptor;
104
105impl UserAgentInterceptor {
106    /// Creates a new `UserAgentInterceptor`
107    pub fn new() -> Self {
108        UserAgentInterceptor
109    }
110}
111
112fn header_values(
113    ua: &AwsUserAgent,
114) -> Result<(HeaderValue, HeaderValue), UserAgentInterceptorError> {
115    // Pay attention to the extremely subtle difference between ua_header and aws_ua_header below...
116    Ok((
117        HeaderValue::try_from(ua.ua_header())?,
118        HeaderValue::try_from(ua.aws_ua_header())?,
119    ))
120}
121
122impl Intercept for UserAgentInterceptor {
123    fn name(&self) -> &'static str {
124        "UserAgentInterceptor"
125    }
126
127    fn read_after_serialization(
128        &self,
129        _context: &BeforeTransmitInterceptorContextRef<'_>,
130        _runtime_components: &RuntimeComponents,
131        cfg: &mut ConfigBag,
132    ) -> Result<(), BoxError> {
133        // Allow for overriding the user agent by an earlier interceptor (so, for example,
134        // tests can use `AwsUserAgent::for_tests()`) by attempting to grab one out of the
135        // config bag before creating one.
136        if cfg.load::<AwsUserAgent>().is_some() {
137            return Ok(());
138        }
139
140        let api_metadata = cfg
141            .load::<ApiMetadata>()
142            .ok_or(UserAgentInterceptorError::MissingApiMetadata)?;
143        let mut ua = AwsUserAgent::new_from_environment(Env::real(), api_metadata.clone());
144
145        let maybe_app_name = cfg.load::<AppName>();
146        if let Some(app_name) = maybe_app_name {
147            ua.set_app_name(app_name.clone());
148        }
149
150        cfg.interceptor_state().store_put(ua);
151
152        Ok(())
153    }
154
155    fn modify_before_signing(
156        &self,
157        context: &mut BeforeTransmitInterceptorContextMut<'_>,
158        runtime_components: &RuntimeComponents,
159        cfg: &mut ConfigBag,
160    ) -> Result<(), BoxError> {
161        let mut ua = cfg
162            .load::<AwsUserAgent>()
163            .expect("`AwsUserAgent should have been created in `read_before_execution`")
164            .clone();
165
166        let mut added_metrics = std::collections::HashSet::new();
167
168        add_metrics_unique!(cfg.load::<SmithySdkFeature>(), &mut ua, &mut added_metrics);
169        add_metrics_unique!(cfg.load::<AwsSdkFeature>(), &mut ua, &mut added_metrics);
170        // The order we emit credential features matters.
171        // Reverse to preserve emission order since StoreAppend pops backwards.
172        add_metrics_unique_reverse!(
173            cfg.load::<AwsCredentialFeature>(),
174            &mut ua,
175            &mut added_metrics
176        );
177
178        let maybe_connector_metadata = runtime_components
179            .http_client()
180            .and_then(|c| c.connector_metadata());
181        if let Some(connector_metadata) = maybe_connector_metadata {
182            let am = AdditionalMetadata::new(Cow::Owned(connector_metadata.to_string()))?;
183            ua.add_additional_metadata(am);
184        }
185
186        let headers = context.request_mut().headers_mut();
187        let (user_agent, x_amz_user_agent) = header_values(&ua)?;
188        headers.append(USER_AGENT, user_agent);
189        headers.append(X_AMZ_USER_AGENT, x_amz_user_agent);
190        Ok(())
191    }
192}
193
194#[cfg(test)]
195mod tests {
196    use super::*;
197    use aws_smithy_runtime_api::client::interceptors::context::{Input, InterceptorContext};
198    use aws_smithy_runtime_api::client::interceptors::Intercept;
199    use aws_smithy_runtime_api::client::orchestrator::HttpRequest;
200    use aws_smithy_runtime_api::client::runtime_components::RuntimeComponentsBuilder;
201    use aws_smithy_types::config_bag::{ConfigBag, Layer};
202    use aws_smithy_types::error::display::DisplayErrorContext;
203
204    fn expect_header<'a>(context: &'a InterceptorContext, header_name: &str) -> &'a str {
205        context
206            .request()
207            .expect("request is set")
208            .headers()
209            .get(header_name)
210            .unwrap()
211    }
212
213    fn context() -> InterceptorContext {
214        let mut context = InterceptorContext::new(Input::doesnt_matter());
215        context.enter_serialization_phase();
216        context.set_request(HttpRequest::empty());
217        let _ = context.take_input();
218        context.enter_before_transmit_phase();
219        context
220    }
221
222    #[test]
223    fn test_overridden_ua() {
224        let rc = RuntimeComponentsBuilder::for_tests().build().unwrap();
225        let mut context = context();
226
227        let mut layer = Layer::new("test");
228        layer.store_put(AwsUserAgent::for_tests());
229        layer.store_put(ApiMetadata::new("unused", "unused"));
230        let mut cfg = ConfigBag::of_layers(vec![layer]);
231
232        let interceptor = UserAgentInterceptor::new();
233        let mut ctx = Into::into(&mut context);
234        interceptor
235            .modify_before_signing(&mut ctx, &rc, &mut cfg)
236            .unwrap();
237
238        let header = expect_header(&context, "user-agent");
239        assert_eq!(AwsUserAgent::for_tests().ua_header(), header);
240        assert!(!header.contains("unused"));
241
242        assert_eq!(
243            AwsUserAgent::for_tests().aws_ua_header(),
244            expect_header(&context, "x-amz-user-agent")
245        );
246    }
247
248    #[test]
249    fn test_default_ua() {
250        let rc = RuntimeComponentsBuilder::for_tests().build().unwrap();
251        let mut context = context();
252
253        let api_metadata = ApiMetadata::new("some-service", "some-version");
254        let mut layer = Layer::new("test");
255        layer.store_put(api_metadata.clone());
256        let mut config = ConfigBag::of_layers(vec![layer]);
257
258        let interceptor = UserAgentInterceptor::new();
259        let ctx = Into::into(&context);
260        interceptor
261            .read_after_serialization(&ctx, &rc, &mut config)
262            .unwrap();
263        let mut ctx = Into::into(&mut context);
264        interceptor
265            .modify_before_signing(&mut ctx, &rc, &mut config)
266            .unwrap();
267
268        let expected_ua = AwsUserAgent::new_from_environment(Env::real(), api_metadata);
269        assert!(
270            expected_ua.aws_ua_header().contains("some-service"),
271            "precondition"
272        );
273        assert_eq!(
274            expected_ua.ua_header(),
275            expect_header(&context, "user-agent")
276        );
277        assert_eq!(
278            expected_ua.aws_ua_header(),
279            expect_header(&context, "x-amz-user-agent")
280        );
281    }
282
283    #[test]
284    fn test_modify_before_signing_no_duplicate_metrics() {
285        let rc = RuntimeComponentsBuilder::for_tests().build().unwrap();
286        let mut context = context();
287
288        let api_metadata = ApiMetadata::new("test-service", "1.0");
289        let mut layer = Layer::new("test");
290        layer.store_put(api_metadata);
291        // Duplicate features
292        layer.store_append(SmithySdkFeature::Waiter);
293        layer.store_append(SmithySdkFeature::Waiter);
294        layer.store_append(AwsSdkFeature::S3Transfer);
295        layer.store_append(AwsSdkFeature::S3Transfer);
296        layer.store_append(AwsCredentialFeature::CredentialsCode);
297        layer.store_append(AwsCredentialFeature::CredentialsCode);
298        let mut config = ConfigBag::of_layers(vec![layer]);
299
300        let interceptor = UserAgentInterceptor::new();
301        let ctx = Into::into(&context);
302        interceptor
303            .read_after_serialization(&ctx, &rc, &mut config)
304            .unwrap();
305        let mut ctx = Into::into(&mut context);
306        interceptor
307            .modify_before_signing(&mut ctx, &rc, &mut config)
308            .unwrap();
309
310        let aws_ua_header = expect_header(&context, "x-amz-user-agent");
311        let metrics_section = aws_ua_header.split(" m/").nth(1).unwrap();
312        let waiter_count = metrics_section.matches("B").count();
313        let s3_transfer_count = metrics_section.matches("G").count();
314        let credentials_code_count = metrics_section.matches("e").count();
315        assert_eq!(
316            1, waiter_count,
317            "Waiter metric should appear only once, but found {waiter_count} occurrences in: {aws_ua_header}",
318        );
319        assert_eq!(1, s3_transfer_count, "S3Transfer metric should appear only once, but found {s3_transfer_count} occurrences in metrics section: {aws_ua_header}");
320        assert_eq!(1, credentials_code_count, "CredentialsCode metric should appear only once, but found {credentials_code_count} occurrences in metrics section: {aws_ua_header}");
321    }
322
323    #[test]
324    fn test_metrics_order_preserved() {
325        use aws_credential_types::credential_feature::AwsCredentialFeature;
326
327        let rc = RuntimeComponentsBuilder::for_tests().build().unwrap();
328        let mut context = context();
329
330        let api_metadata = ApiMetadata::new("test-service", "1.0");
331        let mut layer = Layer::new("test");
332        layer.store_put(api_metadata);
333        layer.store_append(AwsCredentialFeature::CredentialsCode);
334        layer.store_append(AwsCredentialFeature::CredentialsEnvVars);
335        layer.store_append(AwsCredentialFeature::CredentialsProfile);
336        let mut config = ConfigBag::of_layers(vec![layer]);
337
338        let interceptor = UserAgentInterceptor::new();
339        let ctx = Into::into(&context);
340        interceptor
341            .read_after_serialization(&ctx, &rc, &mut config)
342            .unwrap();
343        let mut ctx = Into::into(&mut context);
344        interceptor
345            .modify_before_signing(&mut ctx, &rc, &mut config)
346            .unwrap();
347
348        let aws_ua_header = expect_header(&context, "x-amz-user-agent");
349        let metrics_section = aws_ua_header.split(" m/").nth(1).unwrap();
350
351        assert_eq!(
352            metrics_section, "e,g,n",
353            "AwsCredentialFeature metrics should preserve order"
354        );
355    }
356
357    #[test]
358    fn test_app_name() {
359        let rc = RuntimeComponentsBuilder::for_tests().build().unwrap();
360        let mut context = context();
361
362        let api_metadata = ApiMetadata::new("some-service", "some-version");
363        let mut layer = Layer::new("test");
364        layer.store_put(api_metadata);
365        layer.store_put(AppName::new("my_awesome_app").unwrap());
366        let mut config = ConfigBag::of_layers(vec![layer]);
367
368        let interceptor = UserAgentInterceptor::new();
369        let ctx = Into::into(&context);
370        interceptor
371            .read_after_serialization(&ctx, &rc, &mut config)
372            .unwrap();
373        let mut ctx = Into::into(&mut context);
374        interceptor
375            .modify_before_signing(&mut ctx, &rc, &mut config)
376            .unwrap();
377
378        let app_value = "app/my_awesome_app";
379        let header = expect_header(&context, "user-agent");
380        assert!(
381            !header.contains(app_value),
382            "expected `{header}` to not contain `{app_value}`"
383        );
384
385        let header = expect_header(&context, "x-amz-user-agent");
386        assert!(
387            header.contains(app_value),
388            "expected `{header}` to contain `{app_value}`"
389        );
390    }
391
392    #[test]
393    fn test_api_metadata_missing() {
394        let rc = RuntimeComponentsBuilder::for_tests().build().unwrap();
395        let context = context();
396        let mut config = ConfigBag::base();
397
398        let interceptor = UserAgentInterceptor::new();
399        let ctx = Into::into(&context);
400
401        let error = format!(
402            "{}",
403            DisplayErrorContext(
404                &*interceptor
405                    .read_after_serialization(&ctx, &rc, &mut config)
406                    .expect_err("it should error")
407            )
408        );
409        assert!(
410            error.contains("This is a bug"),
411            "`{error}` should contain message `This is a bug`"
412        );
413    }
414
415    #[test]
416    fn test_api_metadata_missing_with_ua_override() {
417        let rc = RuntimeComponentsBuilder::for_tests().build().unwrap();
418        let mut context = context();
419
420        let mut layer = Layer::new("test");
421        layer.store_put(AwsUserAgent::for_tests());
422        let mut config = ConfigBag::of_layers(vec![layer]);
423
424        let interceptor = UserAgentInterceptor::new();
425        let mut ctx = Into::into(&mut context);
426
427        interceptor
428            .modify_before_signing(&mut ctx, &rc, &mut config)
429            .expect("it should succeed");
430
431        let header = expect_header(&context, "user-agent");
432        assert_eq!(AwsUserAgent::for_tests().ua_header(), header);
433        assert!(!header.contains("unused"));
434
435        assert_eq!(
436            AwsUserAgent::for_tests().aws_ua_header(),
437            expect_header(&context, "x-amz-user-agent")
438        );
439    }
440
441    #[test]
442    fn test_cfg_load_captures_all_feature_layers() {
443        use crate::sdk_feature::AwsSdkFeature;
444
445        // Create a ConfigBag with features in both base layer and interceptor_state
446        let mut base_layer = Layer::new("base");
447        base_layer.store_append(AwsSdkFeature::EndpointOverride);
448
449        let mut config = ConfigBag::of_layers(vec![base_layer]);
450
451        // Store a feature in interceptor_state (simulating what interceptors do)
452        config
453            .interceptor_state()
454            .store_append(AwsSdkFeature::SsoLoginDevice);
455
456        // Verify that cfg.load() captures features from all layers
457        let all_features: Vec<&AwsSdkFeature> = config.load::<AwsSdkFeature>().collect();
458
459        assert_eq!(
460            all_features.len(),
461            2,
462            "cfg.load() should capture features from all layers"
463        );
464        assert!(
465            all_features.contains(&&AwsSdkFeature::EndpointOverride),
466            "should contain feature from base layer"
467        );
468        assert!(
469            all_features.contains(&&AwsSdkFeature::SsoLoginDevice),
470            "should contain feature from interceptor_state"
471        );
472    }
473}
aws_runtime/user_agent/interceptor.rs

aws_runtime/user_agent/
interceptor.rs
