lablup / lablup/backend.ai

Improve i18n and UI text templating support of error messages

Open
#2,029 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
670
Forks
183
Avg merge
17h 7m
Merged PRs (30d)
358

Description

## 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](https://www.rfc-editor.org/rfc/rfc7807) and its successor [RFC-9457](https://www.rfc-editor.org/rfc/rfc9457) as abstracted as subclasses of `aiohttp.web.HTTPError` in [ai.backend.manager.api.exceptions](https://github.com/lablup/backend.ai/blob/main/src/ai/backend/manager/api/exceptions.py) using the _problem identifiers_ (the `type` field) like `https://api.backend.ai/probs/`.

An example from RFC-9457:

```Java
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 (#1678).

JIRA Issue: BA-128

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.