Что такое мета данные в gRPC?

Что такое метаданные в gRPC?

Метаданные в gRPC представляют собой набор дополнительной информации, передаваемой в рамках вызова между клиентом и сервером, но не являющейся частью основного сообщения (запроса или ответа), определенного в Protobuf схеме. Они аналогичны заголовкам (headers) в HTTP и используются для передачи контекстных данных, не относящихся непосредственно к бизнес-логике запроса.

Основные характеристики метаданных

• Ключ-значение: Метаданные организованы как набор пар ключ-значение.
• Типы данных: Значения могут быть строковыми (string) или бинарными ([]byte).
• Направление передачи: Метаданные могут передаваться в обоих направлениях:
  • Client-to-server: Включаются в начальный вызов от клиента.
  • Server-to-client: Передаются сервером вместе с ответом или потоковыми сообщениями.
• Контекст: В Go они интегрируются с объектом context.Context, что позволяет легко передавать их между слоями приложения.

Типичные use cases метаданных

• Аутентификация и авторизация: Передача токенов (JWT, API ключей).
• Трассировка и логирование: Идентификаторы запросов (correlation ID), информация для распределенной трассировки.
• Управление: Индикаторы качества обслуживания (deadline/timeout), метрики.
• Специфичные данные: Язык пользователя (Accept-Language), информация о клиенте (версия приложения).

Работа с метаданными в Go

Для работы с метаданными в gRPC Go используется пакет google.golang.org/grpc/metadata. Основные операции:

1. Отправка метаданных от клиента:

import (
    "context"
    "google.golang.org/grpc/metadata"
)

func callWithMetadata() {
    // Создание метаданных
    md := metadata.New(map[string]string{
        "authorization": "Bearer my_token",
        "client-version": "1.0.0",
    })

    // Прикрепление метаданных к контексту
    ctx := metadata.NewOutgoingContext(context.Background(), md)

    // Вызов RPC с контекстом, содержащим метаданные
    response, err := client.MyMethod(ctx, &request)
}

2. Получение метаданных на сервере:

func (s *MyServer) MyMethod(ctx context.Context, req *MyRequest) (*MyResponse, error) {
    // Извлечение метаданных из контекста
    md, ok := metadata.FromIncomingContext(ctx)
    if !ok {
        return nil, status.Error(codes.InvalidArgument, "metadata not found")
    }

    // Получение конкретного значения (массив строк, так как ключ может иметь множественные значения)
    authHeaders := md.Get("authorization")
    if len(authHeaders) == 0 {
        return nil, status.Error(codes.Unauthenticated, "authorization token required")
    }

    // Использование значения
    token := authHeaders[0]
    // ... дальнейшая обработка
}

3. Отправка метаданных от сервера к клиенту:

Для отправки метаданных в ответе сервер использует trailers или заголовки (headers) в потоковых методах.

// Пример отправки в потоковом RPC (server streaming)
func (s *MyServer) StreamMethod(req *MyRequest, stream MyService_StreamMethodServer) error {
    // Создание и отправка метаданных в начале потока (headers)
    headerMD := metadata.New(map[string]string{"stream-id": "12345"})
    stream.SendHeader(headerMD)

    // Отправка данных
    stream.Send(&MyResponse{Data: "first"})

    // Создание и отправка метаданных в конце потока (trailers)
    trailerMD := metadata.New(map[string]string{"processed-count": "10"})
    stream.SetTrailer(trailerMD)
    return nil
}

Особенности и важные нюансы

• Множественные значения: Ключ может иметь несколько значений (например, несколько заголовков Accept-Language). Метод md.Get() возвращает массив строк.
• Чувствительность к регистру: Ключи в метаданных не чувствительны к регистру. Они преобразуются к нижнему регистру при передаче.
• Бинарные данные: Для передачи бинарных данных используйте ключи с суффиксом -bin. Это гарантирует корректную передачу без преобразования в текст.

  md := metadata.New(map[string]string{"custom-header-bin": string(binaryData)})
  

Метаданные являются мощным инструментом в gRPC, позволяющим реализовать межсервисное взаимодействие с поддержкой безопасности, наблюдаемости и управления без изменения основных контрактов сервисов. Их интеграция с контекстом в Go делает их использование естественным и удобным в рамках архитектуры приложения.