Какие бывают gRPC status codes и как их мапят на ошибки?

1️⃣ Как кратко ответить

gRPC status codes — это набор кодов, используемых для обозначения состояния выполнения RPC вызова. Они включают OK, CANCELLED, UNKNOWN, INVALID_ARGUMENT, DEADLINE_EXCEEDED, NOT_FOUND, ALREADY_EXISTS, PERMISSION_DENIED, RESOURCE_EXHAUSTED, FAILED_PRECONDITION, ABORTED, OUT_OF_RANGE, UNIMPLEMENTED, INTERNAL, UNAVAILABLE, DATA_LOSS и UNAUTHENTICATED. Эти коды мапятся на ошибки, чтобы клиент мог корректно обработать результат вызова, например, повторить запрос или сообщить пользователю об ошибке.

2️⃣ Подробное объяснение темы

gRPC (Google Remote Procedure Call) — это современный фреймворк для удаленного вызова процедур, который позволяет клиентам и серверам взаимодействовать друг с другом через сеть. Важной частью gRPC является система кодов состояния (status codes), которая помогает клиентам и серверам обмениваться информацией о результатах выполнения запросов.

Зачем нужны gRPC status codes?

gRPC status codes позволяют клиенту понять, как завершился вызов: успешно или с ошибкой. Это важно для обработки ошибок, повторных попыток выполнения запросов и информирования пользователей о проблемах. Каждый код состояния соответствует определенной категории ошибок или успешному завершению.

Основные gRPC status codes

1. OK (0): Успешное выполнение запроса. Нет ошибок.
2. CANCELLED (1): Операция была отменена, возможно, пользователем.
3. UNKNOWN (2): Неизвестная ошибка. Обычно это ошибка, не соответствующая ни одному из других кодов.
4. INVALID_ARGUMENT (3): Клиент передал недопустимый аргумент.
5. DEADLINE_EXCEEDED (4): Время выполнения операции истекло до ее завершения.
6. NOT_FOUND (5): Запрашиваемый ресурс не найден.
7. ALREADY_EXISTS (6): Попытка создать ресурс, который уже существует.
8. PERMISSION_DENIED (7): У клиента нет прав на выполнение операции.
9. RESOURCE_EXHAUSTED (8): Исчерпаны ресурсы, например, квота или память.
10. FAILED_PRECONDITION (9): Операция не может быть выполнена в текущем состоянии системы.
11. ABORTED (10): Операция была прервана, например, из-за конфликта.
12. OUT_OF_RANGE (11): Операция попыталась выйти за пределы допустимых значений.
13. UNIMPLEMENTED (12): Операция не поддерживается сервером.
14. INTERNAL (13): Внутренняя ошибка сервера.
15. UNAVAILABLE (14): Сервис временно недоступен.
16. DATA_LOSS (15): Невосстановимая потеря данных.
17. UNAUTHENTICATED (16): Клиент не аутентифицирован.

Как мапят gRPC status codes на ошибки?

gRPC status codes мапятся на ошибки в зависимости от контекста и логики приложения. Например:

• OK: Нет ошибки, можно продолжать работу.
• CANCELLED: Клиент может решить, нужно ли повторить запрос или сообщить пользователю об отмене.
• DEADLINE_EXCEEDED: Клиент может попытаться повторить запрос с увеличенным таймаутом.
• NOT_FOUND: Клиент может сообщить пользователю, что ресурс не найден, или предложить создать его.
• PERMISSION_DENIED: Клиент может запросить у пользователя дополнительные права или сообщить об отсутствии доступа.

Пример обработки gRPC status codes в коде

import grpc
​
def handle_rpc_error(rpc_error):
    status_code = rpc_error.code()
​
    if status_code == grpc.StatusCode.OK:
        print("Operation completed successfully.")
    elif status_code == grpc.StatusCode.CANCELLED:
        print("Operation was cancelled.")
    elif status_code == grpc.StatusCode.DEADLINE_EXCEEDED:
        print("Deadline exceeded. Consider retrying the request.")
    elif status_code == grpc.StatusCode.NOT_FOUND:
        print("Resource not found.")
    elif status_code == grpc.StatusCode.PERMISSION_DENIED:
        print("Permission denied. Check your access rights.")
    else:
        print(f"An error occurred: {status_code.name}")
​
# Пример использования функции
try:
    # Предположим, что `stub` — это gRPC клиент
    response = stub.SomeRpcMethod(request)
except grpc.RpcError as e:
    handle_rpc_error(e)

В этом примере функция handle_rpc_error принимает объект ошибки rpc_error, полученный при выполнении gRPC вызова. Она проверяет код состояния и выводит соответствующее сообщение. Это позволяет клиенту корректно реагировать на различные ситуации, возникающие при взаимодействии с сервером.