Improve i18n and UI text templating support of error messages

[achimnol]

Historical Background

The GUI (including our WebUI) usually comes with an i18n subsystem to provide various UI texts in multiple languages. Such subsystem could be also used to abstract/wrap the low-level error messages to a more user-friendly texts. In contrast, the CLI often just prints the server-provided error messages as-is.

To allow GUI to provide localized and 'softened' user-friendly error messages, it should have its own text resources mapped with individual error messages from the server. This means we need a structured code system to identify all error messages case by case in the client side.

So far, we have adopted the idea of RFC-7807 and its successor RFC-9457 as abstracted as subclasses of aiohttp.web.HTTPError in ai.backend.manager.api.exceptions using the problem identifiers (the type field) like https://api.backend.ai/probs/<slug>.

An example from RFC-9457:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.com/probs/out-of-credit",
 "title": "You do not have enough credit.",
 "detail": "Your current balance is 30, but that costs 50.",
 "instance": "/account/12345/msgs/abc",
 "balance": 30,
 "accounts": ["/account/12345",
              "/account/67890"]
}

Problem

As time goes on, there arose many cases that the frontend UI wants to use its own translation and writing of the error messages instead of directly displaying the title and detail fields of the problem JSON data. Also, the server-side code also began to reuse and share the same problem class (e.g., VFolderOperationFailed) to represent multiple different errors by changing the title and detail fields only.

This has made a confusing situation for both users and our frontend developers because there is no single source of the error message texts to refer and override.

Solution and Direction

We need to divide the shared/reused problem classes and assign explicit, individual problem identifiers to all different raise of API handler errors.

• There will be too many subclasses. We could shrink the number of subclasses to one by introducing a common implementation of RFC-9457.
• Generate/preserve the title and detail fields in the server-side for the clients who does not have UI text mapping subsystems (e.g., CLI).
• Like the above example problem JSON, include error arguments like the target instance ID, related object references, etc. so that the clients who have a UI text mapping subsystem could implement a templated mapping to interpolate them in error message displays.
  • The GUI should fall back to the original title and detail fields if it is not in the text template mapping.
• Make (auto-generate preferably) the full list of all problem identifier occurrences to refer in the documentation.
  • Scan all Python source files and analyze/scan the AST?
  • Consider the plugin codes that are not included in the monorepo.
• Devise a hierarchical naming rule of the problem identifiers, e.g., {target-object-type}-{action}-{problem}.
• Define several common user-defined problem JSON fields to indicate the source of errors (e.g., manager / agent / user workload) and the request ID (Introduce request ID and request context passed through webserver, manager, storage-proxy, and agent #1678).