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