🎨 web-api: New batch of improved user-facing messages (#7944)

Author: pcrespov

.github/prompts/update-user-messages.prompt.md

@@ -18,7 +18,7 @@ error_msg = user_message("Operation failed. Please try again later.")
 
 ## Guidelines for Updating User Messages
 
-When modifying user messages, follow these rules:
+When modifying user messages, follow **as close as possible** these rules:
 
 1. **Version Tracking**: Every modification to a user message must include an incremented `_version` parameter:
 
@@ -43,7 +43,7 @@ When modifying user messages, follow these rules:
    user_message("Unable to load project.", _version=1)
    ```
 
-3. **Message Style**: Follow *strictly* the guidelines in `${workspaceFolder}/docs/user-messages-guidelines.md`
+3. **Message Style**: Follow **strictly** the guidelines in `${workspaceFolder}/docs/user-messages-guidelines.md`
 
 4. **Preserve Context**: Ensure the modified message conveys the same meaning and context as the original.
 
@@ -56,17 +56,19 @@ When modifying user messages, follow these rules:
    # After
    user_message("Your session has expired. Please log in again.", _version=3)
    ```
+6. **Replace 'Study' by 'Project'**: If the message contains the word 'Study', replace it with 'Project' to align with our terminology.
+
 
 ## Examples
 
 ### Example 1: Simple Message Update
 
 ```python
 # Before
-error_dialog(user_message("Failed to save changes."))
+error_dialog(user_message("Failed to save changes in this study."))
 
 # After
-error_dialog(user_message("Unable to save your changes. Please try again.", _version=1))
+error_dialog(user_message("Unable to save your changes in this project.", _version=1))
 ```
 
 ### Example 2: F-string Message Update

packages/service-library/src/servicelib/aiohttp/rest_middlewares.py

@@ -36,7 +36,8 @@
 DEFAULT_API_VERSION = "v0"
 _FMSG_INTERNAL_ERROR_USER_FRIENDLY = user_message(
     "We apologize for the inconvenience. "
-    "The issue has been recorded, please report it if it persists."
+    "The issue has been recorded, please report it if it persists.",
+    _version=1,
 )
 
 

services/web/server/src/simcore_service_webserver/catalog/_constants.py

@@ -1,11 +1,14 @@
 from typing import Final
 
+from common_library.user_messages import user_message
+
 from ..constants import MSG_TRY_AGAIN_OR_SUPPORT
 
-MSG_CATALOG_SERVICE_UNAVAILABLE: Final[str] = (
+MSG_CATALOG_SERVICE_UNAVAILABLE: Final[str] = user_message(
     # Most likely the director service is down or misconfigured so the user is asked to try again later.
-    "This service is temporarily unavailable. The incident was logged and will be investigated. "
-    + MSG_TRY_AGAIN_OR_SUPPORT
+    "The catalog service is currently unavailable. This issue has been logged and will be investigated. "
+    + MSG_TRY_AGAIN_OR_SUPPORT,
+    _version=1,
 )
 
 

services/web/server/src/simcore_service_webserver/constants.py

@@ -1,5 +1,6 @@
 # pylint:disable=unused-import
 
+from sys import version
 from typing import Final
 
 from common_library.user_messages import user_message
@@ -39,7 +40,7 @@
 # main index route name = front-end
 INDEX_RESOURCE_NAME: Final[str] = "get_cached_frontend_index"
 
-MSG_UNDER_DEVELOPMENT: Final[str] = (
+MSG_UNDER_DEVELOPMENT: Final[str] = user_message(
     "Under development. Use WEBSERVER_DEV_FEATURES_ENABLED=1 to enable current implementation"
 )
 
@@ -48,7 +49,7 @@
 
 
 MSG_TRY_AGAIN_OR_SUPPORT: Final[str] = user_message(
-    "Please try again shortly. If the issue persists, contact support."
+    "Please try again shortly. If the issue persists, contact support.", _version=1
 )
 
 __all__: tuple[str, ...] = (

services/web/server/src/simcore_service_webserver/director_v2/_controller/_rest_exceptions.py

@@ -87,11 +87,17 @@ async def _handler_director_service_error_as_503_or_4xx(
 _TO_HTTP_ERROR_MAP: ExceptionToHttpErrorMap = {
     UserDefaultWalletNotFoundError: HttpErrorInfo(
         status.HTTP_404_NOT_FOUND,
-        user_message("Default wallet not found but necessary for computations"),
+        user_message(
+            "A default wallet is required for running computations but could not be found.",
+            _version=1,
+        ),
     ),
     WalletNotEnoughCreditsError: HttpErrorInfo(
         status.HTTP_402_PAYMENT_REQUIRED,
-        user_message("Wallet does not have enough credits for computations. {reason}"),
+        user_message(
+            "Your wallet does not have sufficient credits to run this computation. {reason}",
+            _version=1,
+        ),
     ),
 }
 

services/web/server/src/simcore_service_webserver/folders/_common/exceptions_handlers.py

@@ -32,49 +32,56 @@
 _TO_HTTP_ERROR_MAP: ExceptionToHttpErrorMap = {
     FolderNotFoundError: HttpErrorInfo(
         status.HTTP_404_NOT_FOUND,
-        user_message("Folder was not found"),
+        user_message("The requested folder could not be found.", _version=1),
     ),
     WorkspaceNotFoundError: HttpErrorInfo(
         status.HTTP_404_NOT_FOUND,
-        user_message("Workspace was not found"),
+        user_message("The requested workspace could not be found.", _version=1),
     ),
     FolderAccessForbiddenError: HttpErrorInfo(
         status.HTTP_403_FORBIDDEN,
-        user_message("Does not have access to this folder"),
+        user_message("You do not have permission to access this folder.", _version=1),
     ),
     WorkspaceAccessForbiddenError: HttpErrorInfo(
         status.HTTP_403_FORBIDDEN,
-        user_message("Does not have access to this workspace"),
+        user_message(
+            "You do not have permission to access this workspace.", _version=1
+        ),
     ),
     WorkspaceFolderInconsistencyError: HttpErrorInfo(
         status.HTTP_403_FORBIDDEN,
-        user_message("This folder does not exist in this workspace"),
+        user_message(
+            "This folder is not available in the selected workspace.", _version=1
+        ),
     ),
     FolderValueNotPermittedError: HttpErrorInfo(
         status.HTTP_409_CONFLICT,
-        user_message("Provided folder value is not permitted: {reason}"),
+        user_message("The folder operation cannot be completed: {reason}", _version=1),
     ),
     FoldersValueError: HttpErrorInfo(
         status.HTTP_409_CONFLICT,
-        user_message("Invalid folder value set: {reason}"),
+        user_message("The folder configuration is invalid: {reason}", _version=1),
     ),
     ProjectInvalidRightsError: HttpErrorInfo(
         status.HTTP_403_FORBIDDEN,
         user_message(
-            "Access Denied: You do not have permission to move the project with UUID: {project_uuid}. Tip: Copy and paste the UUID into the search bar to locate the project."
+            "You do not have permission to move the project with UUID: {project_uuid}. To locate this project, copy and paste the UUID into the search bar.",
+            _version=1,
         ),
     ),
     # Trashing
     ProjectRunningConflictError: HttpErrorInfo(
         status.HTTP_409_CONFLICT,
         user_message(
-            "One or more studies in this folder are in use and cannot be trashed. Please stop all services first and try again"
+            "Cannot move folder to trash because it contains projects that are currently running. Please stop all running services first and try again.",
+            _version=2,
         ),
     ),
     ProjectStoppingError: HttpErrorInfo(
         status.HTTP_503_SERVICE_UNAVAILABLE,
         user_message(
-            "Something went wrong while stopping running services in studies within this folder before trashing. Aborting trash."
+            "Something went wrong while stopping running services in projects within this folder before trashing. Aborting trash.",
+            _version=2,
         ),
     ),
 }

services/web/server/src/simcore_service_webserver/groups/_common/exceptions_handlers.py

@@ -24,32 +24,40 @@
 _TO_HTTP_ERROR_MAP: ExceptionToHttpErrorMap = {
     UserNotFoundError: HttpErrorInfo(
         status.HTTP_404_NOT_FOUND,
-        user_message("User {uid} or {email} not found"),
+        user_message(
+            "The user with ID {uid} or email {email} could not be found.", _version=1
+        ),
     ),
     GroupNotFoundError: HttpErrorInfo(
         status.HTTP_404_NOT_FOUND,
-        user_message("Group {gid} not found"),
+        user_message("The group with ID {gid} could not be found.", _version=1),
     ),
     UserInGroupNotFoundError: HttpErrorInfo(
         status.HTTP_404_NOT_FOUND,
-        user_message("User not found in group {gid}"),
+        user_message("The user is not a member of group {gid}.", _version=1),
     ),
     UserAlreadyInGroupError: HttpErrorInfo(
         status.HTTP_409_CONFLICT,
-        user_message("User is already in group {gid}"),
+        user_message("The user is already a member of group {gid}.", _version=1),
     ),
     UserInsufficientRightsError: HttpErrorInfo(
         status.HTTP_403_FORBIDDEN,
-        user_message("Insufficient rights for {permission} access to group {gid}"),
+        user_message(
+            "You do not have sufficient rights for {permission} access to group {gid}.",
+            _version=1,
+        ),
     ),
     # scicrunch
     InvalidRRIDError: HttpErrorInfo(
         status.HTTP_409_CONFLICT,
-        user_message("Invalid RRID {rrid}"),
+        user_message("The RRID {rrid} is not valid.", _version=1),
     ),
     ScicrunchError: HttpErrorInfo(
         status.HTTP_409_CONFLICT,
-        user_message("Cannot get RRID since scicrunch.org service is not reachable."),
+        user_message(
+            "Unable to retrieve RRID information because the scicrunch.org service is currently unavailable.",
+            _version=1,
+        ),
     ),
 }
 

services/web/server/src/simcore_service_webserver/invitations/errors.py

@@ -1,16 +1,20 @@
 """
-    API plugin errors
+API plugin errors
 """
 
+from common_library.user_messages import user_message
 
 from ..errors import WebServerBaseError
 
-MSG_INVALID_INVITATION_URL = "Link seems corrupted or incomplete"
-MSG_INVITATION_ALREADY_USED = "This invitation was already used"
+MSG_INVALID_INVITATION_URL = user_message(
+    "The invitation link appears to be corrupted or incomplete.", _version=1
+)
+MSG_INVITATION_ALREADY_USED = user_message(
+    "This invitation has already been used and cannot be used again.", _version=1
+)
 
 
-class InvitationsError(WebServerBaseError, ValueError):
-    ...
+class InvitationsError(WebServerBaseError, ValueError): ...
 
 
 class InvalidInvitationError(InvitationsError):

services/web/server/src/simcore_service_webserver/licenses/_common/exceptions_handlers.py

@@ -18,20 +18,30 @@
 _TO_HTTP_ERROR_MAP: ExceptionToHttpErrorMap = {
     LicensedItemNotFoundError: HttpErrorInfo(
         status.HTTP_404_NOT_FOUND,
-        user_message("Market item {licensed_item_id} not found."),
+        user_message(
+            "The requested market item '{licensed_item_id}' could not be found.",
+            _version=1,
+        ),
     ),
     WalletAccessForbiddenError: HttpErrorInfo(
         status.HTTP_403_FORBIDDEN,
-        user_message("Credit account {wallet_id} forbidden."),
+        user_message(
+            "You do not have permission to access credit account '{wallet_id}'.",
+            _version=1,
+        ),
     ),
     WalletNotEnoughCreditsError: HttpErrorInfo(
         status.HTTP_402_PAYMENT_REQUIRED,
-        user_message("Not enough credits in the credit account."),
+        user_message(
+            "Your credit account does not have sufficient funds to complete this purchase.",
+            _version=1,
+        ),
     ),
     LicensedItemPricingPlanMatchError: HttpErrorInfo(
         status.HTTP_400_BAD_REQUEST,
         user_message(
-            "The provided pricing plan does not match the one associated with the licensed item."
+            "The selected pricing plan is not valid for this licensed item. Please choose a different plan.",
+            _version=1,
         ),
     ),
 }