implement API for username changes

Author: avirshup

crates/crates_io_database/src/models/abandoned_username.rs

@@ -0,0 +1,27 @@
+use crate::schema::abandoned_usernames;
+use chrono::{DateTime, Utc};
+use diesel::prelude::*;
+
+#[derive(Debug, Clone, Identifiable, HasQuery)]
+#[diesel(
+    table_name = abandoned_usernames,
+    check_for_backend(diesel::pg::Pg),
+)]
+pub struct AbandonedUsername {
+    pub id: i64,
+    pub username: String,
+    pub previous_user_id: Option<i32>,
+    pub adopted_at: Option<DateTime<Utc>>,
+    pub abandoned_at: DateTime<Utc>,
+    pub available_at: DateTime<Utc>,
+}
+
+#[derive(Insertable, Debug)]
+#[diesel(table_name = abandoned_usernames, check_for_backend(diesel::pg::Pg))]
+pub struct NewAbandonedUsername<'a> {
+    pub username: &'a str,
+    pub previous_user_id: Option<i32>,
+    pub adopted_at: Option<&'a DateTime<Utc>>,
+    pub abandoned_at: &'a DateTime<Utc>,
+    pub available_at: &'a DateTime<Utc>,
+}

crates/crates_io_database/src/models/mod.rs

@@ -1,3 +1,4 @@
+pub use self::abandoned_username::{AbandonedUsername, NewAbandonedUsername};
 pub use self::action::{NewVersionOwnerAction, VersionAction, VersionOwnerAction};
 pub use self::cache_tags_backfill::NewCacheTagsBackfillRow;
 pub use self::category::{Category, CrateCategory, NewCategory};
@@ -24,6 +25,7 @@ pub use self::version::{NewVersion, TopVersions, Version};
 
 pub mod helpers;
 
+mod abandoned_username;
 mod action;
 mod cache_tags_backfill;
 pub mod category;

crates/crates_io_validation/src/lib.rs

@@ -86,6 +86,30 @@ pub enum InvalidDependencyName {
     Char(char, String),
 }
 
+pub const MAX_USERNAME_LENGTH: usize = 39;
+
+// Only allows usernames to contain alphanumeric characters ([a-zA-Z0-9]), hyphens (-), and underscores (_).
+// Doesn't allow usernames to start with a hyphen or underscore.
+// Doesn't allow usernames to exceed 39 characters.
+
+#[derive(Debug, Eq, PartialEq, thiserror::Error)]
+pub enum InvalidUsername {
+    #[error("the username `{0}` is too long (max {MAX_USERNAME_LENGTH} characters)")]
+    TooLong(String),
+    #[error("username cannot be empty")]
+    Empty,
+    #[error(
+        "invalid character `{0}` in username: `{1}`, \
+        the first character must be an ASCII alphanumeric character"
+    )]
+    Start(char, String),
+    #[error(
+        "invalid character `{0}` in username: `{1}`, \
+        characters must be ASCII alphanumeric characters, `-`, or `_`"
+    )]
+    Char(char, String),
+}
+
 // Validates the name is a valid crate name.
 // This is also used for validating the name of dependencies.
 // So the `for_what` parameter is used to indicate what the name is used for.
@@ -212,6 +236,28 @@ pub fn validate_feature(name: &str) -> Result<(), InvalidFeature> {
     }
 }
 
+pub fn validate_username(username: &str) -> Result<(), InvalidUsername> {
+    if username.chars().count() > MAX_USERNAME_LENGTH {
+        return Err(InvalidUsername::TooLong(username.into()));
+    }
+
+    let mut chars = username.chars();
+    let Some(first_char) = chars.next() else {
+        return Err(InvalidUsername::Empty);
+    };
+    if !first_char.is_ascii_alphanumeric() {
+        return Err(InvalidUsername::Start(first_char, username.into()));
+    }
+
+    for ch in chars {
+        if !(ch.is_ascii_alphanumeric() || ch == '-' || ch == '_') {
+            return Err(InvalidUsername::Char(ch, username.into()));
+        }
+    }
+
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -367,4 +413,41 @@ mod tests {
             InvalidDependencyName::StartWithDigit("0foo".into()).into()
         );
     }
+
+    #[test]
+    fn test_validate_username() {
+        use super::{InvalidUsername, MAX_USERNAME_LENGTH};
+
+        assert_ok!(validate_username("foo"));
+        assert_err_eq!(
+            validate_username("京"),
+            InvalidUsername::Start('京', "京".into())
+        );
+        assert_err_eq!(validate_username(""), InvalidUsername::Empty);
+        assert_err_eq!(
+            validate_username("💝"),
+            InvalidUsername::Start('💝', "💝".into())
+        );
+
+        assert_ok!(validate_username("foo_underscore"));
+        assert_ok!(validate_username("foo-dash"));
+        assert_err_eq!(
+            validate_username("foo+plus"),
+            InvalidUsername::Char('+', "foo+plus".into())
+        );
+        assert_err_eq!(
+            validate_username("_foo"),
+            InvalidUsername::Start('_', "_foo".into())
+        );
+        assert_err_eq!(
+            validate_username("-foo"),
+            InvalidUsername::Start('-', "-foo".into())
+        );
+        assert_ok!(validate_username("123"));
+
+        assert_err_eq!(
+            validate_username("o".repeat(MAX_USERNAME_LENGTH + 1).as_str()),
+            InvalidUsername::TooLong("o".repeat(MAX_USERNAME_LENGTH + 1).as_str().into())
+        );
+    }
 }

packages/crates-io-api-client/schema.d.ts

@@ -4106,6 +4106,7 @@ export interface operations {
                     user: {
                         email?: string | null;
                         publish_notifications?: boolean | null;
+                        username?: string | null;
                     };
                 };
             };

src/controllers/user/update.rs

@@ -3,12 +3,17 @@ use crate::auth::AuthCheck;
 use crate::controllers::helpers::OkResponse;
 use crate::email::EmailMessage;
 use crate::models::NewEmail;
-use crate::schema::users;
+use crate::schema::{abandoned_usernames, reserved_usernames, users};
 use crate::util::errors::{AppResult, bad_request, server_error};
+
 use axum::Json;
 use axum::extract::Path;
+use chrono::{DateTime, SecondsFormat, TimeDelta, Utc};
+use crates_io_database::fns::canon_username;
+use crates_io_database::models::NewAbandonedUsername;
+use crates_io_validation::validate_username;
 use diesel::prelude::*;
-use diesel_async::RunQueryDsl;
+use diesel_async::{AsyncConnection, AsyncPgConnection, RunQueryDsl};
 use http::request::Parts;
 use lettre::Address;
 use minijinja::context;
@@ -24,10 +29,14 @@ pub struct UserUpdate {
 
 #[derive(Deserialize, utoipa::ToSchema)]
 pub struct User {
+    username: Option<String>,
     email: Option<String>,
     publish_notifications: Option<bool>,
 }
 
+/// Amount of time after a username is given up before it can be re-used
+const USERNAME_COOLDOWN: TimeDelta = TimeDelta::days(30);
+
 /// Update user settings.
 ///
 /// This endpoint allows users to update their email address and publish notifications settings.
@@ -97,6 +106,55 @@ pub async fn update_user(
         }
     }
 
+    if let Some(newname) = &user_update.user.username
+        && newname != &user.username
+    {
+        // stop immediately if username is invalid
+        validate_username(newname).map_err(bad_request)?;
+
+        conn.transaction(async |conn|
+            {
+                // checks to ensure the new username is available
+                if is_reserved_username(newname, conn).await? {
+                    return Err(bad_request(format!("the username `{newname}` is reserved")));
+                }
+                if username_conflict(newname, user.id, conn).await?
+                {
+                    return Err(bad_request(format!(
+                        "the username `{newname}` is not available"
+                    )));
+                }
+                if let Some(available_at) = username_has_cooldown(newname, conn).await? {
+                    return Err(bad_request(format!(
+                        "The username `{}` was recently in use. This username will be available after {}.",
+                        newname,
+                        available_at.to_rfc3339_opts(SecondsFormat::Secs, true)
+                    )));
+                }
+
+                // build and apply updates to both `users` and `abandoned_usernames` tables
+                let now = Utc::now();
+                let available_at = now + USERNAME_COOLDOWN;
+                let abandonment_record = NewAbandonedUsername {  username: &user.username,
+                    previous_user_id: Some(user.id),
+                    adopted_at: user.current_username_adopted_at.as_ref(),
+                    abandoned_at: &now,
+                    available_at: &available_at
+                };
+
+                diesel::update(user)
+                    .set((users::username.eq(newname), users::current_username_adopted_at.eq(now)))
+                    .execute(conn)
+                    .await?;
+                diesel::insert_into(abandoned_usernames::table)
+                    .values(abandonment_record)
+                    .execute(conn)
+                    .await?;
+
+                Ok(())
+            }).await?;
+    }
+
     if let Some(user_email) = &user_update.user.email {
         let user_email = user_email.trim();
 
@@ -141,3 +199,64 @@ pub async fn update_user(
 
     Ok(OkResponse::new())
 }
+
+/// Returns true if any users *besides the current one*
+/// have a username that conflicts with this one
+async fn username_conflict(
+    username: &str,
+    user_id: i32,
+    conn: &mut AsyncPgConnection,
+) -> Result<bool, diesel::result::Error> {
+    let in_use_name_query: Option<String> = users::table
+        .filter(users::id.ne(user_id))
+        .filter(canon_username(users::username).eq(canon_username(username)))
+        .select(users::username)
+        .first(conn)
+        .await
+        .optional()?;
+    if let Some(_in_use_name) = in_use_name_query {
+        Ok(true)
+    } else {
+        Ok(false)
+    }
+}
+
+async fn is_reserved_username(
+    username: &str,
+    mut conn: &mut AsyncPgConnection,
+) -> Result<bool, diesel::result::Error> {
+    let reserved_name_query: Option<String> = reserved_usernames::table
+        .filter(canon_username(reserved_usernames::username).eq(canon_username(username)))
+        .select(reserved_usernames::username)
+        .first(&mut conn)
+        .await
+        .optional()?;
+
+    if let Some(_reserved_name) = reserved_name_query {
+        Ok(true)
+    } else {
+        Ok(false)
+    }
+}
+
+async fn username_has_cooldown(
+    username: &str,
+    conn: &mut AsyncPgConnection,
+) -> Result<Option<DateTime<Utc>>, diesel::result::Error> {
+    let abandoned_name_query: Option<(String, DateTime<Utc>)> = abandoned_usernames::table
+        .filter(canon_username(abandoned_usernames::username).eq(canon_username(username)))
+        .filter(abandoned_usernames::available_at.gt(Utc::now()))
+        .select((
+            abandoned_usernames::username,
+            abandoned_usernames::available_at,
+        ))
+        .first(conn)
+        .await
+        .optional()?;
+
+    if let Some((_abandoned_name, available_at)) = abandoned_name_query {
+        Ok(Some(available_at))
+    } else {
+        Ok(None)
+    }
+}