change user flag (#3076)

<!-- PR description-->
As part of handling share mailbox-
Introduced new flag - `mailbox` and deprecated existing `user` flag
This is to handle wider group of mailbox types.

#### Does this PR need a docs update or release note?

- [x] ✅ Yes, it's included

#### Type of change

<!--- Please check the type of change your PR introduces: --->
- [x] 🌻 Feature

#### Issue(s)

<!-- Can reference multiple issues. Use one of the following "magic words" - "closes, fixes" to auto-close the Github issue. -->
* #<issue>

#### Test Plan

<!-- How will this be tested prior to merging.-->
- [x] 💪 Manual

.github/workflows/load_test.yml

@@ -86,15 +86,15 @@ jobs:
           CORSO_M365_LOAD_TEST_USER_ID: ${{ secrets.CORSO_M365_LOAD_TEST_USER_ID }}
         run: |
           go run . exchange emails \
-          --user ${{ env.CORSO_M365_LOAD_TEST_USER_ID }} \
+          --mailbox ${{ env.CORSO_M365_LOAD_TEST_USER_ID }} \
           --destination lt_${{ env.NOW }} \
           --count 10
           go run . exchange contacts \
-          --user ${{ env.CORSO_M365_LOAD_TEST_USER_ID }} \
+          --mailbox ${{ env.CORSO_M365_LOAD_TEST_USER_ID }} \
           --destination lt_${{ env.NOW }} \
           --count 10
           go run . exchange events \
-          --user ${{ env.CORSO_M365_LOAD_TEST_USER_ID }} \
+          --mailbox ${{ env.CORSO_M365_LOAD_TEST_USER_ID }} \
           --destination lt_${{ env.NOW }} \
           --count 10
 

.github/workflows/sanity-test.yaml

@@ -112,7 +112,7 @@ jobs:
           CORSO_M365_LOAD_TEST_USER_ID: ${{ secrets.CORSO_M365_LOAD_TEST_USER_ID }}
         run: |
           go run . exchange emails \
-          --user ${{ env.CORSO_M365_TEST_USER_ID }} \
+          --mailbox ${{ env.CORSO_M365_TEST_USER_ID }} \
           --tenant ${{ env.AZURE_TENANT_ID }} \
           --destination Corso_Restore_st_${{ steps.repo-init.outputs.result }} \
           --count 4
@@ -123,11 +123,11 @@ jobs:
         run: |
           ./corso backup create exchange \
           --no-stats \
-          --user "${CORSO_M365_TEST_USER_ID}" \
+          --mailbox "${CORSO_M365_TEST_USER_ID}" \
-          --hide-progress \
+           --hide-progress \
-          --data 'email' \
+           --data 'email' \
-          --json \
+            --json \
-          2>&1 | tee $TEST_RESULT/backup_exchange.txt 
+            2>&1 | tee $TEST_RESULT/backup_exchange.txt 
 
           resultjson=$(sed -e '1,/Completed Backups/d' $TEST_RESULT/backup_exchange.txt ) 
 
@@ -200,7 +200,7 @@ jobs:
           ./corso backup create exchange \
           --no-stats \
           --hide-progress \
-          --user "${CORSO_M365_TEST_USER_ID}" \
+          --mailbox "${CORSO_M365_TEST_USER_ID}" \
           --json \
           2>&1 | tee $TEST_RESULT/backup_exchange_incremental.txt 
 

src/cli/backup/exchange.go

@@ -32,38 +32,38 @@ const (
 
 const (
 	exchangeServiceCommand                 = "exchange"
-	exchangeServiceCommandCreateUseSuffix  = "--user <email> | '" + utils.Wildcard + "'"
+	exchangeServiceCommandCreateUseSuffix  = "--mailbox <email> | '" + utils.Wildcard + "'"
 	exchangeServiceCommandDeleteUseSuffix  = "--backup <backupId>"
 	exchangeServiceCommandDetailsUseSuffix = "--backup <backupId>"
 )
 
 const (
 	exchangeServiceCommandCreateExamples = `# Backup all Exchange data for Alice
-corso backup create exchange --user alice@example.com
+corso backup create exchange --mailbox alice@example.com
 
 # Backup only Exchange contacts for Alice and Bob
-corso backup create exchange --user alice@example.com,bob@example.com --data contacts
+corso backup create exchange --mailbox alice@example.com,bob@example.com --data contacts
 
 # Backup all Exchange data for all M365 users 
-corso backup create exchange --user '*'`
+corso backup create exchange --mailbox '*'`
 
 	exchangeServiceCommandDeleteExamples = `# Delete Exchange backup with ID 1234abcd-12ab-cd34-56de-1234abcd
 corso backup delete exchange --backup 1234abcd-12ab-cd34-56de-1234abcd`
 
 	exchangeServiceCommandDetailsExamples = `# Explore Alice's items in backup 1234abcd-12ab-cd34-56de-1234abcd 
-corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --user alice@example.com
+corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --mailbox alice@example.com
 
 # Explore Alice's emails with subject containing "Hello world" in folder "Inbox" from a specific backup 
 corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
-    --user alice@example.com --email-subject "Hello world" --email-folder Inbox
+    --mailbox alice@example.com --email-subject "Hello world" --email-folder Inbox
 
 # Explore Bobs's events occurring after start of 2022 from a specific backup
 corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
-    --user bob@example.com --event-starts-after 2022-01-01T00:00:00
+    --mailbox bob@example.com --event-starts-after 2022-01-01T00:00:00
 
 # Explore Alice's contacts with name containing Andy from a specific backup
 corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
-    --user alice@example.com --contact-name Andy`
+    --mailbox alice@example.com --contact-name Andy`
 )
 
 // called by backup.go to map subcommands to provider-specific handling.
@@ -83,7 +83,7 @@ func addExchangeCommands(cmd *cobra.Command) *cobra.Command {
 
 		// Flags addition ordering should follow the order we want them to appear in help and docs:
 		// More generic (ex: --user) and more frequently used flags take precedence.
-		utils.AddUserFlag(c)
+		utils.AddMailBoxFlag(c)
 		utils.AddDataFlag(c, []string{dataEmail, dataContacts, dataEvents}, false)
 		options.AddFetchParallelismFlag(c)
 		options.AddFailFastFlag(c)
@@ -207,7 +207,7 @@ func exchangeBackupCreateSelectors(userIDs, cats []string) *selectors.ExchangeBa
 
 func validateExchangeBackupCreateFlags(userIDs, cats []string) error {
 	if len(userIDs) == 0 {
-		return clues.New("--user requires one or more email addresses or the wildcard '*'")
+		return clues.New("--user/--mailbox requires one or more email addresses or the wildcard '*'")
 	}
 
 	for _, d := range cats {

src/cli/cli.go

@@ -90,11 +90,28 @@ func preRun(cc *cobra.Command, args []string) error {
 			options.Control())
 	}
 
+	// handle deprecated user flag in Backup exchange command
+	if cc.CommandPath() == "corso backup create exchange" {
+		handleMailBoxFlag(ctx, cc, flagSl)
+	}
+
 	log.Infow("cli command", "command", cc.CommandPath(), "flags", flagSl, "version", version.CurrentVersion())
 
 	return nil
 }
 
+func handleMailBoxFlag(ctx context.Context, c *cobra.Command, flagNames []string) {
+	if !slices.Contains(flagNames, "user") && !slices.Contains(flagNames, "mailbox") {
+		print.Errf(ctx, "either --user or --mailbox flag is required")
+		os.Exit(1)
+	}
+
+	if slices.Contains(flagNames, "user") && slices.Contains(flagNames, "mailbox") {
+		print.Err(ctx, "cannot use both [mailbox, user] flags in the same command")
+		os.Exit(1)
+	}
+}
+
 // Handler for flat calls to `corso`.
 // Produces the same output as `corso --help`.
 func handleCorsoCmd(cmd *cobra.Command, args []string) error {

src/cli/utils/flags.go

@@ -45,9 +45,10 @@ const (
 	BackupFN       = "backup"
 	CategoryDataFN = "data"
 
-	SiteFN   = "site"    // site only accepts WebURL values
+	SiteFN    = "site"    // site only accepts WebURL values
-	SiteIDFN = "site-id" // site-id accepts actual site ids
+	SiteIDFN  = "site-id" // site-id accepts actual site ids
-	UserFN   = "user"
+	UserFN    = "user"
+	MailBoxFN = "mailbox"
 
 	LibraryFN = "library"
 	FileFN    = "file"
@@ -124,6 +125,23 @@ func AddUserFlag(cmd *cobra.Command) {
 	cobra.CheckErr(cmd.MarkFlagRequired(UserFN))
 }
 
+// AddMailBoxFlag adds the --user and --mailbox flag.
+func AddMailBoxFlag(cmd *cobra.Command) {
+	flags := cmd.Flags()
+
+	flags.StringSliceVar(
+		&UserFV,
+		UserFN, nil,
+		"Backup a specific user's data; accepts '"+Wildcard+"' to select all users.")
+
+	cobra.CheckErr(flags.MarkDeprecated(UserFN, fmt.Sprintf("use --%s instead", MailBoxFN)))
+
+	flags.StringSliceVar(
+		&UserFV,
+		MailBoxFN, nil,
+		"Backup a specific mailbox's data; accepts '"+Wildcard+"' to select all mailbox.")
+}
+
 // AddSiteIDFlag adds the --site-id flag, which accepts site ID values.
 // This flag is hidden, since we expect users to prefer the --site url
 // and do not want to encourage confusion.

website/docs/quickstart.md

@@ -125,7 +125,7 @@ you initialized the Corso repository, you might need to [connect to it again](..
 
   ```powershell
   # Backup your inbox
-  .\corso backup create exchange --user <your exchange email address>
+  .\corso backup create exchange --mailbox <your exchange email address>
   ```
 
 </TabItem>
@@ -133,7 +133,7 @@ you initialized the Corso repository, you might need to [connect to it again](..
 
   ```bash
   # Backup your inbox
-  ./corso backup create exchange --user <your exchange email address>
+  ./corso backup create exchange --mailbox <your exchange email address>
   ```
 
 </TabItem>
@@ -143,7 +143,7 @@ you initialized the Corso repository, you might need to [connect to it again](..
 `# Backup your inbox
 docker run --env-file $HOME/.corso/corso.env \\
   --volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\
-  backup create exchange --user <your exchange email address>`
+  backup create exchange --mailbox <your exchange email address>`
 }</CodeBlock>
 
 </TabItem>