gRPC Streaming: потоковая передача данных

gRPC Streaming: потоковая передача данных

gRPC поддерживает четыре типа RPC: Unary (один запрос - один ответ, тот самый вариант, на котором поднимали первый сервер и клиент), Server streaming (один запрос - много ответов), Client streaming (много запросов - один ответ), Bidirectional (много в обе стороны). Streaming - мощный инструмент для real-time приложений, файлов и подписок на события.

Четыре типа RPC: unary, server streaming, client streaming, bidirectional

Server Streaming

Один запрос от клиента, много сообщений от сервера. Подходит для логов, прогресса, real-time-уведомлений.

import "google/protobuf/timestamp.proto";

service LogService {
  rpc StreamLogs(StreamLogsRequest) returns (stream LogEntry);
}

message StreamLogsRequest {}

message LogEntry {
  google.protobuf.Timestamp timestamp = 1;
  string level = 2;
  string message = 3;
}
func (s *logServer) StreamLogs(req *pb.StreamLogsRequest, stream pb.LogService_StreamLogsServer) error {
    for i := 0; i < 100; i++ {
        select {
        case <-stream.Context().Done():
            return stream.Context().Err()  // клиент отменил
        default:
        }

        if err := stream.Send(&pb.LogEntry{
            Timestamp: timestamppb.Now(),
            Level:     "INFO",
            Message:   fmt.Sprintf("Log %d", i),
        }); err != nil {
            return err
        }
        time.Sleep(100 * time.Millisecond)
    }
    return nil
}

В PHP серверный стриминг штатно недоступен. gRPC-сервер на RoadRunner (spiral/roadrunner-grpc) обслуживает только unary-методы: воркер получает одно сообщение и обязан вернуть одно сообщение. PHP-FPM с его моделью «запрос-ответ» для долгоживущего стрима не подходит вовсе.

Если поток нужно отдавать из PHP-приложения, есть два честных пути:

  • вынести стриминговый метод в отдельный сервис на Go (или другом языке с полноценным gRPC-сервером);
  • выбрать другой транспорт: SSE, WebSocket или брокер сообщений.

Зато PHP-клиент через ext-grpc стримы поддерживает - пример ниже.

import time
from collections.abc import Iterator

import grpc
from google.protobuf.timestamp_pb2 import Timestamp

import log_pb2 as pb
import log_pb2_grpc as pb_grpc


class LogServer(pb_grpc.LogServiceServicer):
    def StreamLogs(self, request: pb.StreamLogsRequest, context: grpc.ServicerContext) -> Iterator[pb.LogEntry]:
        for i in range(100):
            if not context.is_active():
                return  # клиент отменил

            now = Timestamp()
            now.GetCurrentTime()
            yield pb.LogEntry(timestamp=now, level="INFO", message=f"Log {i}")
            time.sleep(0.1)

Server-streaming метод - генератор: каждый yield отправляет сообщение, выход из функции закрывает стрим. Отмену клиентом проверяем через context.is_active() между сообщениями.

Клиент:

stream, _ := client.StreamLogs(ctx, &pb.StreamLogsRequest{})
for {
    entry, err := stream.Recv()
    if err == io.EOF {
        break
    }
    if err != nil {
        return err
    }
    fmt.Printf("[%s] %s\n", entry.Level, entry.Message)
}

Server закрывает стрим, возвращая nil из метода. Клиент видит это как io.EOF на Recv.

<?php
declare(strict_types=1);

use Log\LogServiceClient;
use Log\StreamLogsRequest;

final readonly class LogConsumer
{
    public function __construct(
        private LogServiceClient $client,
    ) {}

    public function tail(): void
    {
        $call = $this->client->StreamLogs(new StreamLogsRequest());

        foreach ($call->responses() as $entry) {
            printf('[%s] %s%s', $entry->getLevel(), $entry->getMessage(), "\n");
        }

        $status = $call->getStatus();
        if ($status->code !== Grpc\STATUS_OK) {
            throw new RuntimeException('stream failed: ' . $status->details);
        }
    }
}

PHP-клиент работает через ext-grpc: BaseStub отдаёт объект ServerStreamingCall, у которого есть метод responses() (Generator). Конец стрима - выход из цикла.

import grpc


def tail_logs(client: pb_grpc.LogServiceStub) -> None:
    """Печатает поток логов; grpc.RpcError уходит наверх как есть.

    Как `return err` в Go: не заворачиваем в RuntimeError, иначе вызывающий
    потеряет тип и err.code() (UNAVAILABLE, DEADLINE_EXCEEDED...).
    """
    for entry in client.StreamLogs(pb.StreamLogsRequest()):
        print(f"[{entry.level}] {entry.message}")


try:
    tail_logs(client)
except grpc.RpcError as err:
    print(f"stream failed: {err.code()} {err.details()}")

Server закрывает стрим, когда генератор на сервере завершается. Клиент получает итератор: конец стрима - обычный выход из for, ошибка со статусом - исключение grpc.RpcError прямо из итерации.

Client Streaming

Много сообщений от клиента, один ответ. Идеально для загрузки файлов, batch-импорта.

service FileService {
  rpc Upload(stream FileChunk) returns (UploadResponse);
}

message FileChunk { bytes data = 1; }
message UploadResponse {
  int64 size = 1;
  string checksum = 2;
}
func (s *fileServer) Upload(stream pb.FileService_UploadServer) error {
    var totalBytes int64
    h := sha256.New()

    for {
        chunk, err := stream.Recv()
        if err == io.EOF {
            return stream.SendAndClose(&pb.UploadResponse{
                Size:     totalBytes,
                Checksum: hex.EncodeToString(h.Sum(nil)),
            })
        }
        if err != nil {
            return err
        }
        totalBytes += int64(len(chunk.Data))
        h.Write(chunk.Data)
    }
}

SendAndClose отправляет ответ и закрывает стрим. До этого момента сервер не отвечает - он накапливает.

В PHP client-streaming доступен только на стороне клиента: BaseStub из ext-grpc возвращает ClientStreamingCall, в который складываются чанки через write(). Принять такой стрим PHP-сервер на RoadRunner не может (он обслуживает только unary), поэтому сервер здесь - на Go, как выше. Для крупных загрузок (видео, бэкапы) из PHP-приложения разумной альтернативой остаётся обычный multipart-upload через Symfony. Клиент на PHP:

<?php
declare(strict_types=1);

use File\FileChunk;
use File\FileServiceClient;
use File\UploadResponse;

final readonly class FileUploader
{
    public function __construct(
        private FileServiceClient $client,
    ) {}

    /** @param iterable<string> $chunks */
    public function upload(iterable $chunks): UploadResponse
    {
        $call = $this->client->Upload();

        foreach ($chunks as $bytes) {
            $call->write((new FileChunk())->setData($bytes));
        }

        [$response, $status] = $call->wait();
        if ($status->code !== Grpc\STATUS_OK) {
            throw new RuntimeException('upload failed: ' . $status->details);
        }
        return $response;
    }
}

Bidirectional Streaming

Полный дуплекс: обе стороны шлют независимо. Подходит для чата, real-time-игр, торгов.

service ChatService {
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

message ChatMessage {
  string user = 1;
  string content = 2;
}
func (s *chatServer) Chat(stream pb.ChatService_ChatServer) error {
    for {
        msg, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }

        // Эхо всем подписчикам или просто обратно
        if err := stream.Send(&pb.ChatMessage{
            User:    "bot",
            Content: "Echo: " + msg.Content,
        }); err != nil {
            return err
        }
    }
}
<?php
declare(strict_types=1);

use Chat\ChatMessage;
use Chat\ChatServiceClient;

// Сервер bidi на PHP (RoadRunner) не поднять - он обслуживает только unary.
// Клиент через ext-grpc работает: BidiStreamingCall даёт write(), writesDone() и read().
$call = $client->Chat();

foreach (['hi', 'how are you?'] as $text) {
    $call->write((new ChatMessage())->setUser('jdoe')->setContent($text));
}
$call->writesDone(); // закрываем свою половину стрима (аналог CloseSend в Go)

while (($reply = $call->read()) !== null) {
    printf("%s: %s\n", $reply->getUser(), $reply->getContent());
}

$status = $call->getStatus();
if ($status->code !== Grpc\STATUS_OK) {
    throw new RuntimeException('chat failed: ' . $status->details);
}

Это клиент к Go-серверу выше. Вызовы ext-grpc блокирующие, поэтому писать и читать по-настоящему параллельно в одном PHP-процессе не получится: сначала отправили пачку, потом читаем ответы.

from collections.abc import Iterator

import grpc

import chat_pb2 as pb
import chat_pb2_grpc as pb_grpc


class ChatServer(pb_grpc.ChatServiceServicer):
    def Chat(self, request_iterator: Iterator[pb.ChatMessage], context: grpc.ServicerContext) -> Iterator[pb.ChatMessage]:
        # Входящий стрим - итератор; цикл заканчивается, когда клиент закрыл send-side (EOF).
        for msg in request_iterator:
            # Эхо всем подписчикам или просто обратно
            yield pb.ChatMessage(user="bot", content=f"Echo: {msg.content}")

Bidi-метод получает итератор входящих сообщений и сам является генератором исходящих. В таком виде чтение и запись чередуются; как читать и писать по-настоящему параллельно - ниже, в разделе про concurrent send/receive.

Send и Recv работают независимо: можно одновременно читать в одной горутине и писать в другой. В PHP так не выйдет: серверных стримов нет, а клиент ext-grpc блокирующий.

Flow control и backpressure

HTTP/2 имеет встроенный flow control: каждый поток имеет окно (window size). Sender не может отправить больше, чем позволяет окно. Это даёт автоматическое backpressure: если клиент медленно читает, сервер замедляется тоже.

// Большое окно для streaming с большим throughput
grpcServer := grpc.NewServer(
    grpc.InitialWindowSize(1024*1024),       // 1MB stream window
    grpc.InitialConnWindowSize(2*1024*1024), // 2MB connection window
)

Осторожно: по умолчанию grpc-go подбирает окно сам, по замеру пропускной способности канала (BDP estimation), и может разогнать его до 16MB. Явная установка InitialWindowSize этот механизм отключает, и «большое» окно в 1MB легко окажется меньше автоматического. Меняйте окна только после замеров.

В PHP размеры окон HTTP/2 не настраиваются из приложения. Для unary-сервера на RoadRunner транспортные лимиты задаются в .rr.yaml, обычно дефолтов хватает:

# .rr.yaml
grpc:
    listen: tcp://0.0.0.0:50051
    proto:
        - proto/log.proto
    max_send_msg_size: 4   # MB
    max_recv_msg_size: 16  # MB
    max_connection_age: 0s
    max_connection_idle: 0s
    pool:
        num_workers: 8
        max_jobs: 1000

При типовом backpressure-сценарии (быстрый sender, медленный receiver) sender естественным образом затормозится. Не нужно вручную управлять очередями - HTTP/2 делает это в транспорте.

Stream lifecycle и errors

Стрим может закрыться четырьмя способами:

  • Нормальное закрытие (return nil из server-метода или EOF на client side)
  • Ошибка с status (return status.Error с кодом - клиент получит ошибку)
  • Cancellation (клиент отменил context - сервер видит через ctx.Done())
  • Network failure (потеря соединения - обе стороны получают ошибку)

Превратить внутреннюю ошибку в понятный клиенту status, залогировать каждое сообщение стрима, поймать панику до того, как она уронит процесс - всё это одинаково для любого стрима, поэтому выносится в stream-interceptor, а не дублируется в каждом методе.

for {
    msg, err := stream.Recv()
    switch {
    case err == nil:
        // обработка
    case err == io.EOF:
        return nil
    case status.Code(err) == codes.Canceled:
        // клиент отменил
        return err
    default:
        slog.Error("stream recv", "err", err)
        return err
    }
}
<?php
declare(strict_types=1);

// Клиентская сторона (ext-grpc): статус стрима доступен после чтения всех сообщений
$call = $client->StreamLogs(new StreamLogsRequest());
foreach ($call->responses() as $entry) {
    // обработка $entry
}

$status = $call->getStatus();
match ($status->code) {
    Grpc\STATUS_OK => null,                                    // нормальное закрытие
    Grpc\STATUS_CANCELLED => $logger->info('stream cancelled'),
    default => $logger->error('stream failed', ['code' => $status->code, 'err' => $status->details]),
};

В PHP стрим бывает только на стороне клиента. Конец стрима - выход из foreach, а причину закрытия (успех, отмена, ошибка сервера или сети) показывает getStatus().

import logging
from collections.abc import Iterator

import grpc

logger = logging.getLogger(__name__)


def Chat(self, request_iterator: Iterator[pb.ChatMessage], context: grpc.ServicerContext) -> None:
    try:
        for msg in request_iterator:
            ...  # обработка
        return  # EOF, клиент закрыл send-side
    except grpc.RpcError as err:
        match err.code():
            case grpc.StatusCode.CANCELLED:
                logger.info("client cancelled")
            case _:
                logger.error("stream recv", extra={"err": err.details()})
        raise

EOF - штатный конец for по request_iterator; отмена и сетевая ошибка приходят исключением grpc.RpcError с кодом в err.code().

Concurrent send/receive

В bidirectional часто запускают goroutines для send и receive параллельно:

go func() {
    for {
        select {
        case <-stream.Context().Done():
            return // handler завершился или клиент отключился - выходим, иначе горутина утечёт
        case msg := <-outbound:
            if err := stream.Send(msg); err != nil {
                return
            }
        }
    }
}()

for {
    msg, err := stream.Recv()
    if err != nil {
        return err
    }
    inbound <- msg
}

stream.Send и stream.Recv thread-safe раздельно, но нельзя делать одновременные Send из двух горутин - нужен mutex или единый канал для исходящих.

Прямого аналога на PHP нет. Серверных стримов RoadRunner не поддерживает, а клиент ext-grpc блокирующий: write() и read() выполняются по очереди в одном потоке. Если нужен настоящий дуплекс (чат, телеметрия с командами), эту часть системы пишут на Go, а PHP-приложение общается с ней через unary-вызовы или брокер сообщений.

# Полный дуплекс на asyncio (grpc.aio): две независимые задачи вместо двух горутин.
# В синхронном grpcio то же самое делается потоком на send и queue.Queue вместо asyncio.Queue.
import asyncio
from collections.abc import AsyncIterator

import grpc


async def Chat(
    self,
    request_iterator: AsyncIterator[pb.ChatMessage],
    context: grpc.aio.ServicerContext,
) -> None:
    outbound: asyncio.Queue[pb.ChatMessage] = asyncio.Queue()
    inbound: asyncio.Queue[pb.ChatMessage] = asyncio.Queue()

    async def sender() -> None:
        while True:
            msg = await outbound.get()
            try:
                await context.write(msg)
            except grpc.aio.AioRpcError:
                return

    send_task = asyncio.create_task(sender())
    try:
        # Главная задача читает
        async for msg in request_iterator:
            await inbound.put(msg)
    finally:
        send_task.cancel()

Здесь использован «ручной» вариант bidi из grpc.aio: метод ничего не yield-ит, а пишет через context.write(). Чтение и запись thread-safe раздельно, но одновременные write() из нескольких задач недопустимы - все исходящие идут через одну очередь, как через единый канал в Go.

Когда использовать какой тип

ℹ️ Выбор паттерна

Unary - большинство CRUD-операций. Server streaming - логи, real-time-уведомления, прогресс долгой операции. Client streaming - загрузка файлов, batch-импорт. Bidirectional - чат, real-time-игры, IoT-телеметрия с командами.

Decision matrix

Сценарий                                  Тип RPC               Почему
──────────────────────────                ───────────────       ───────────────────────────
CRUD: создать, получить, обновить         Unary                 один запрос → один ответ;
                                                                 классика, не усложняй
Список из 10K записей с фильтрами          Unary с pagination   проще, чем server stream
                                                                 (offset/cursor)
Список без верхней границы (логи          Server streaming      сервер сам решает, когда
realtime, тикер цен, прогресс долгой                            закончить; backpressure
операции)                                                       работает автоматически
Загрузка файла, batch-импорт              Client streaming      клиент шлёт чанки; сервер
ETL-задания (1K событий → 1 ответ)                              отвечает в конце
Чат, multiplayer-игры, биржевой          Bidirectional         обе стороны независимо
order book, IoT-телеметрия                                      шлют - синхронизация на
с обратными командами                                            уровне HTTP/2 streams
Webhook-уведомления извне                 НЕ gRPC: HTTP POST   gRPC требует HTTP/2-клиента,
                                                                 partner-системы редко его держат
SSE-подобный broadcast на тысячи          Server streaming      работает, но для веба часто
веб-клиентов                              + gRPC-Web ИЛИ SSE   проще: SSE/WebSocket в браузере

Антипаттерны streaming

  • Эмулировать pub/sub через bidirectional: HTTP/2-стрим - это одно соединение, не очередь сообщений. При падении соединения вы теряете состояние. Нужен pub/sub - берите Kafka/NATS/Redis Streams.
  • Стримить «навсегда»: HTTP/2 ping/keepalive поможет, но прокси и LB могут разрывать долгие соединения (idle timeout 60s-5min). Делайте reconnect-логику или периодические keepalive-сообщения.
  • Client streaming для маленьких пакетов: если у вас 10 объектов - отправьте repeated Item в одном Unary-запросе. Streaming имеет смысл при сотнях/тысячах чанков или неизвестной длине.

Мини-практика

Реализуй сервис загрузки файлов: клиент отправляет файл чанками через client streaming, сервер возвращает размер и SHA256-checksum. Проверь поведение при отмене контекста на стороне клиента - сервер должен корректно прерваться. Затем сделай bidirectional chat-сервис с broadcast-ом сообщений всем подключённым клиентам через map[string]grpc.ServerStream.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.