1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

/*
 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 * SPDX-License-Identifier: Apache-2.0
 */

//! New-type for a configurable app name.

use std::borrow::Cow;
use std::error::Error;
use std::fmt;
use std::sync::atomic::{AtomicBool, Ordering};

static APP_NAME_LEN_RECOMMENDATION_WARN_EMITTED: AtomicBool = AtomicBool::new(false);

/// App name that can be configured with an AWS SDK client to become part of the user agent string.
///
/// This name is used to identify the application in the user agent that gets sent along with requests.
///
/// The name may only have alphanumeric characters and any of these characters:
/// ```text
/// !#$%&'*+-.^_`|~
/// ```
/// Spaces are not allowed.
///
/// App names are recommended to be no more than 50 characters.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct AppName(Cow<'static, str>);

impl AsRef<str> for AppName {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

impl fmt::Display for AppName {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl AppName {
    /// Creates a new app name.
    ///
    /// This will return an `InvalidAppName` error if the given name doesn't meet the
    /// character requirements. See [`AppName`] for details on these requirements.
    pub fn new(app_name: impl Into<Cow<'static, str>>) -> Result<Self, InvalidAppName> {
        let app_name = app_name.into();

        fn valid_character(c: char) -> bool {
            match c {
                _ if c.is_ascii_alphanumeric() => true,
                '!' | '#' | '$' | '%' | '&' | '\'' | '*' | '+' | '-' | '.' | '^' | '_' | '`'
                | '|' | '~' => true,
                _ => false,
            }
        }
        if !app_name.chars().all(valid_character) {
            return Err(InvalidAppName);
        }
        if app_name.len() > 50 {
            if let Ok(false) = APP_NAME_LEN_RECOMMENDATION_WARN_EMITTED.compare_exchange(
                false,
                true,
                Ordering::Acquire,
                Ordering::Relaxed,
            ) {
                tracing::warn!(
                    "The `app_name` set when configuring the SDK client is recommended \
                     to have no more than 50 characters."
                )
            }
        }
        Ok(Self(app_name))
    }
}

/// Error for when an app name doesn't meet character requirements.
///
/// See [`AppName`] for details on these requirements.
#[derive(Debug)]
#[non_exhaustive]
pub struct InvalidAppName;

impl Error for InvalidAppName {}

impl fmt::Display for InvalidAppName {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "The app name can only have alphanumeric characters, or any of \
             '!' |  '#' |  '$' |  '%' |  '&' |  '\\'' |  '*' |  '+' |  '-' | \
             '.' |  '^' |  '_' |  '`' |  '|' |  '~'"
        )
    }
}

#[cfg(test)]
mod tests {
    use super::AppName;
    use crate::app_name::APP_NAME_LEN_RECOMMENDATION_WARN_EMITTED;
    use std::sync::atomic::Ordering;

    #[test]
    fn validation() {
        assert!(AppName::new("asdf1234ASDF!#$%&'*+-.^_`|~").is_ok());
        assert!(AppName::new("foo bar").is_err());
        assert!(AppName::new("🚀").is_err());
    }

    #[tracing_test::traced_test]
    #[test]
    fn log_warn_once() {
        // Pre-condition: make sure we start in the expected state of having never logged this
        assert!(!APP_NAME_LEN_RECOMMENDATION_WARN_EMITTED.load(Ordering::Relaxed));

        // Verify a short app name doesn't log
        AppName::new("not-long").unwrap();
        assert!(!logs_contain(
            "is recommended to have no more than 50 characters"
        ));
        assert!(!APP_NAME_LEN_RECOMMENDATION_WARN_EMITTED.load(Ordering::Relaxed));

        // Verify a long app name logs
        AppName::new("greaterthanfiftycharactersgreaterthanfiftycharacters").unwrap();
        assert!(logs_contain(
            "is recommended to have no more than 50 characters"
        ));
        assert!(APP_NAME_LEN_RECOMMENDATION_WARN_EMITTED.load(Ordering::Relaxed));

        // Now verify it only logs once ever

        // HACK: there's no way to reset tracing-test, so just
        // reach into its internals and clear it manually
        tracing_test::internal::GLOBAL_BUF.lock().unwrap().clear();

        AppName::new("greaterthanfiftycharactersgreaterthanfiftycharacters").unwrap();
        assert!(!logs_contain(
            "is recommended to have no more than 50 characters"
        ));
    }
}