Merge branch 'master' into 1922-ensure-no-hang-in-api-server

Author: bisgaard-itis

.github/copilot-instructions.md

@@ -51,5 +51,5 @@ This document provides guidelines and best practices for using GitHub Copilot in
 
 - [Python Coding Conventions](../docs/coding-conventions.md)
 - [Environment Variables Guide](../docs/env-vars.md)
-- [Steps to Upgrade Python](../docs/steps-to-upgrade-python.md)
 - [Pydantic Annotated fields](../docs/llm-prompts/pydantic-annotated-fields.md)
+- [Steps to Upgrade Python](../docs/steps-to-upgrade-python.md)

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

@@ -0,0 +1,92 @@
+---
+mode: 'edit'
+description: 'Update user messages'
+---
+
+This prompt guide is for updating user-facing messages in ${file} or ${selection}
+
+## What is a User Message?
+
+A user message is any string that will be displayed to end-users of the application.
+In our codebase, these messages are marked with the `user_message` function:
+
+```python
+from common_library.user_messages import user_message
+
+error_msg = user_message("Operation failed. Please try again later.")
+```
+
+## Guidelines for Updating User Messages
+
+When modifying user messages, follow these rules:
+
+1. **Version Tracking**: Every modification to a user message must include an incremented `_version` parameter:
+
+   ```python
+   # Before modification
+   user_message("Error: Unable to connect to the server.")
+
+   # After modification, add _version or increment it if it already exists
+   user_message("Currently unable to establish connection to the server.", _version=1)
+   ```
+
+2. **F-String Preservation**: When modifying messages that use f-strings, preserve all parameters and their formatting:
+
+   ```python
+   # Before
+   user_message(f"Project {project_name} could not be loaded.")
+
+   # After (correct)
+   user_message(f"Unable to load project {project_name}.", _version=1)
+
+   # After (incorrect - lost the parameter)
+   user_message("Unable to load project.", _version=1)
+   ```
+
+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.
+
+5. **Incremental Versioning**: If a message already has a version, increment it by 1:
+
+   ```python
+   # Before
+   user_message("Session expired.", _version=2)
+
+   # After
+   user_message("Your session has expired. Please log in again.", _version=3)
+   ```
+
+## Examples
+
+### Example 1: Simple Message Update
+
+```python
+# Before
+error_dialog(user_message("Failed to save changes."))
+
+# After
+error_dialog(user_message("Unable to save your changes. Please try again.", _version=1))
+```
+
+### Example 2: F-string Message Update
+
+```python
+# Before
+raise ValueError(user_message(f"Invalid input parameter: {param_name}"))
+
+# After
+raise ValueError(user_message(f"The parameter '{param_name}' contains a value that is not allowed.", _version=1))
+```
+
+### Example 3: Already Versioned Message
+
+```python
+# Before
+return HttpErrorInfo(status.HTTP_404_NOT_FOUND, user_message("User not found.", _version=1))
+
+# After
+return HttpErrorInfo(status.HTTP_404_NOT_FOUND, user_message("The requested user could not be found.", _version=2))
+```
+
+Remember: The goal is to improve clarity and helpfulness for end-users while maintaining accurate versioning for tracking changes.

docs/messages-guidelines.md renamed to docs/user-messages-guidelines.md

@@ -1,6 +1,6 @@
-# Error and Warning Message Guidelines
+# User Message Guidelines
 
-These guidelines ensure that messages are user-friendly, clear, and helpful while maintaining a professional tone. 🚀
+These guidelines ensure that error and warnings user-facing messages are user-friendly, clear, and helpful while maintaining a professional tone. 🚀
 
 Some details:
 

packages/common-library/src/common_library/user_messages.py

@@ -0,0 +1,11 @@
+def user_message(msg: str, *, _version: int | None = None) -> str:
+    """Marks a message as user-facing
+
+    Arguments:
+        msg -- human-friendly string that follows docs/user-messages-guidelines.md
+        _version -- version number to track changes to messages; increment when modifying an existing message
+
+    Returns:
+        The original message string, allowing it to be used inline in code
+    """
+    return msg

packages/common-library/tests/test_user_messages.py

@@ -0,0 +1,6 @@
+from common_library.user_messages import user_message
+
+
+def test_user_message() -> None:
+
+    assert user_message("This is a user message") == "This is a user message"

packages/models-library/src/models_library/projects.py

@@ -8,9 +8,6 @@
 from uuid import UUID
 
 from common_library.basic_types import DEFAULT_FACTORY
-from models_library.basic_types import ConstrainedStr
-from models_library.folders import FolderID
-from models_library.workspaces import WorkspaceID
 from pydantic import (
     BaseModel,
     ConfigDict,
@@ -21,8 +18,11 @@
 )
 
 from .basic_regex import DATE_RE, UUID_RE_BASE
+from .basic_types import ConstrainedStr
 from .emails import LowerCaseEmailStr
+from .folders import FolderID
 from .groups import GroupID
+from .products import ProductName
 from .projects_access import AccessRights, GroupIDStr
 from .projects_nodes import Node
 from .projects_nodes_io import NodeIDStr
@@ -33,6 +33,7 @@
     none_to_empty_str_pre_validator,
 )
 from .utils.enums import StrAutoEnum
+from .workspaces import WorkspaceID
 
 ProjectID: TypeAlias = UUID
 CommitID: TypeAlias = int
@@ -147,6 +148,25 @@ def _convert_sql_alchemy_enum(cls, v):
     )
 
 
+class ProjectListAtDB(BaseProjectModel):
+    id: int
+    type: ProjectType
+    template_type: ProjectTemplateType | None
+    prj_owner: int | None
+    ui: dict[str, Any] | None
+    classifiers: list[ClassifierID] | None
+    dev: dict[str, Any] | None
+    quality: dict[str, Any]
+    published: bool | None
+    hidden: bool
+    workspace_id: WorkspaceID | None
+    trashed: datetime | None
+    trashed_by: UserID | None
+    trashed_explicitly: bool
+    product_name: ProductName
+    folder_id: FolderID | None
+
+
 class Project(BaseProjectModel):
     # NOTE: This is the pydantic pendant of project-v0.0.1.json used in the API of the webserver/webclient
     # NOT for usage with DB!!

packages/models-library/src/models_library/projects_nodes.py

@@ -168,7 +168,7 @@ class Node(BaseModel):
         ),
     ] = None
 
-    thumbnail: Annotated[
+    thumbnail: Annotated[  # <-- (DEPRECATED) Can be removed
         str | HttpUrl | None,
         Field(
             description="url of the latest screenshot of the node",
@@ -232,18 +232,18 @@ class Node(BaseModel):
     ] = DEFAULT_FACTORY
 
     output_node: Annotated[bool | None, Field(deprecated=True, alias="outputNode")] = (
-        None
+        None  # <-- (DEPRECATED) Can be removed
     )
 
-    output_nodes: Annotated[
+    output_nodes: Annotated[  # <-- (DEPRECATED) Can be removed
         list[NodeID] | None,
         Field(
             description="Used in group-nodes. Node IDs of those connected to the output",
             alias="outputNodes",
         ),
     ] = None
 
-    parent: Annotated[
+    parent: Annotated[  # <-- (DEPRECATED) Can be removed
         NodeID | None,
         Field(
             description="Parent's (group-nodes') node ID s. Used to group",

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

@@ -13,6 +13,7 @@
 from aiohttp.web_response import StreamResponse
 from common_library.error_codes import create_error_code
 from common_library.json_serialization import json_dumps, json_loads
+from common_library.user_messages import user_message
 from models_library.rest_error import ErrorGet, ErrorItemType, LogMessageType
 
 from ..logging_errors import create_troubleshotting_log_kwargs
@@ -31,7 +32,7 @@
 from .web_exceptions_extension import get_http_error_class_or_none
 
 DEFAULT_API_VERSION = "v0"
-_FMSG_INTERNAL_ERROR_USER_FRIENDLY = (
+_FMSG_INTERNAL_ERROR_USER_FRIENDLY = user_message(
     "We apologize for the inconvenience. "
     "The issue has been recorded, please report it if it persists."
 )

packages/service-library/src/servicelib/fastapi/long_running_tasks/_client.py

@@ -120,7 +120,7 @@ def __init__(self, app: FastAPI, async_client: AsyncClient, base_url: str):
         """
         self.app = app
         self._async_client = async_client
-        self._base_url = base_url
+        self.base_url = base_url
 
     @property
     def _client_configuration(self) -> ClientConfiguration:
@@ -129,7 +129,7 @@ def _client_configuration(self) -> ClientConfiguration:
 
     def _get_url(self, path: str) -> str:
         url_path = f"{self._client_configuration.router_prefix}{path}".lstrip("/")
-        url = TypeAdapter(AnyHttpUrl).validate_python(f"{self._base_url}{url_path}")
+        url = TypeAdapter(AnyHttpUrl).validate_python(f"{self.base_url}{url_path}")
         return f"{url}"
 
     @retry_on_http_errors

packages/service-library/src/servicelib/fastapi/long_running_tasks/_context_manager.py

@@ -1,12 +1,13 @@
 import asyncio
-from asyncio.log import logger
+import logging
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from typing import Any, Final
 
 from pydantic import PositiveFloat
+from servicelib.logging_errors import create_troubleshotting_log_message
 
-from ...long_running_tasks.errors import TaskClientTimeoutError
+from ...long_running_tasks.errors import TaskClientTimeoutError, TaskExceptionError
 from ...long_running_tasks.models import (
     ProgressCallback,
     ProgressMessage,
@@ -16,6 +17,8 @@
 )
 from ._client import Client
 
+_logger = logging.getLogger(__name__)
+
 # NOTE: very short running requests are involved
 MAX_CONCURRENCY: Final[int] = 10
 
@@ -96,7 +99,7 @@ async def periodic_task_result(
 
     async def _status_update() -> TaskStatus:
         task_status: TaskStatus = await client.get_task_status(task_id)
-        logger.debug("Task status %s", task_status.model_dump_json())
+        _logger.debug("Task status %s", task_status.model_dump_json())
         await progress_manager.update(
             task_id=task_id,
             message=task_status.task_progress.message,
@@ -114,7 +117,7 @@ async def _wait_for_task_result() -> Any:
 
     try:
         result = await asyncio.wait_for(_wait_for_task_result(), timeout=task_timeout)
-        logger.debug("%s, %s", f"{task_id=}", f"{result=}")
+        _logger.debug("%s, %s", f"{task_id=}", f"{result=}")
 
         yield result
     except TimeoutError as e:
@@ -124,3 +127,13 @@ async def _wait_for_task_result() -> Any:
             timeout=task_timeout,
             exception=e,
         ) from e
+    except Exception as e:
+        error = TaskExceptionError(task_id=task_id, exception=e, traceback="")
+        _logger.warning(
+            create_troubleshotting_log_message(
+                user_error_msg=f"{task_id=} raised an exception",
+                error=e,
+                tip=f"Check the logs of the service responding to '{client.base_url}'",
+            )
+        )
+        raise error from e