Стриминговые ответы: ReadableStream, SSE для LLM-интерфейсов и прокси, которые их буферизуют

Возврат стрима из route handler

Route handler возвращает web Response, а телом Response может быть ReadableStream — в момент возврата Next немедленно отправляет заголовки и сбрасывает чанки по мере того, как ваш код их enqueue-ит. Никто не ждёт «завершения» функции:

// app/api/chat/route.ts — проксируем LLM, переотправляем токены как SSE
export async function POST(request: Request) {
  const { prompt } = await request.json();
  const upstream = await llm.stream(prompt);          // async iterable of tokens
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async pull(controller) {
      const { value, done } = await upstream.next();
      if (done) {
        controller.enqueue(encoder.encode("data: [DONE]\n\n"));
        controller.close();
        return;
      }
      controller.enqueue(encoder.encode(`data: ${JSON.stringify(value)}\n\n`));
    },
    cancel() {
      upstream.return?.();   // client disconnected — stop paying the LLM
    },
  });

  return new Response(stream, {
    headers: {
      "content-type": "text/event-stream",
      "cache-control": "no-cache, no-transform",
      "x-accel-buffering": "no",                     // nginx: do not buffer
    },
  });
}

Три детали в этом коде несут продакшен-вес. Колбэк pull — крючок backpressure, о нём ниже. Колбэк cancel срабатывает при отключении клиента; без него пользователь, закрывший вкладку на середине ответа, оставляет хендлер радостно потреблять (и оплачивать) остаток LLM-генерации. А заголовки — броня против девятисекундного спиннера из Hook.

SSE: скучный, правильный протокол для потоков токенов

Для LLM-интерфейсов нужна конвенция фрейминга — у сырых чанков нет границ сообщений; токен может приехать разрезанным между двумя сетевыми чтениями. Server-Sent Events — устоявшийся ответ: content type text/event-stream, сообщения в рамке data: <payload>\n\n, в браузере читается EventSource (авто-реконнект, докачка через Last-Event-ID) или, как делают все AI SDK для POST-тел, чтением response.body с парсером. SSE выигрывает у WebSockets здесь потому, что поток токенов однонаправленный: без upgrade-рукопожатия, чистая HTTP-семантика (работает сквозь стандартные прокси и мультиплексирование HTTP/2), тривиально возобновляем и доступен через обычный fetch. WebSockets оправдывают свою сложность, только когда клиент должен часто слать сообщения по тому же соединению.

Сценарий отказа, уникальный для SSE, — порча фрейминга: если вы выдадите payload с сырым переводом строки, не разрезав его по data:-строкам, клиентский парсер молча обрежет сообщения — JSON-кодируйте каждый payload (как выше), и проблема исчезнет.

Backpressure: производить в темпе потребителя

У стрима есть продюсер (ваш LLM-прокси, курсор базы, читатель файла) и потребитель (соединение пользователя — часто медленный телефон на слабом Wi-Fi). Когда продюсер быстрее, разница накапливается в памяти вашего сервера. Web streams решают это pull-моделью: рантайм вызывает ваш pull(controller), когда во внутренней очереди есть место (отслеживается controller.desiredSize, освобождается по мере того, как потребитель вычитывает байты), — корректно написанный источник генерирует только по запросу. Антипаттерн — обход модели: колбэк start() с циклом, который enqueue-ит целый скан таблицы, или прокачка быстрого upstream в медленного клиента без ожидания writer-а:

// НЕВЕРНО: backpressure игнорируется — весь курсор оказывается в памяти
start(controller) {
  for await (const row of hugeCursor) controller.enqueue(encode(row));
}
// ВЕРНО: pull() читает по одному элементу по запросу со стороны потребителя
async pull(controller) {
  const { value, done } = await hugeCursor.next();
  done ? controller.close() : controller.enqueue(encode(value));
}

Для потоков токенов ставки низки — токены крошечные, а люди читают медленно. Для эндпоинтов экспорта данных (CSV-дампы, хвосты логов) backpressure — это разница между ровным профилем памяти в 30 МБ и OOM-убитым подом, когда один клиент с медленным соединением запросил экспорт на 2 ГБ. Если вы компонуете трансформации, pipeThrough/pipeTo пропагируют backpressure за вас; утекает он в самописных циклах.

Два стриминга, одно слово — и строй буферизаторов

Next.js стримит в двух разных смыслах, и их смешение путает отладку. Suspense-стриминг страниц — это App Router, прогрессивно рендерящий HTML: оболочка уходит сразу, рендерятся фолбэки loading.tsx/<Suspense>, а опоздавшие серверные компоненты приезжают чанками вне порядка, которые inline-скрипты вставляют на место. Его единица — UI; протоколом владеет фреймворк. Хендлерный стриминг данных — этот урок — это вы возвращаете байты, которые потребляет клиентский код: SSE-события, NDJSON-строки, CSV-ряды. Его единица — данные; фрейминг, заголовки и отмена — ваши. Они делят транспорт (chunked HTTP) и потому делят врага: всё, что буферизует.

Строй, хоп за хопом. nginx: proxy_buffering on по умолчанию — отключается per-response заголовком X-Accel-Buffering: no. Сжатие: middleware gzip/brotli накапливает вход для окон сжатия; Cache-Control: no-transform велит благовоспитанным посредникам не перекодировать, а собственный слой сжатия обязан исключить text/event-stream. CDN: некоторые буферизуют или даже кешируют стриминговые ответы, если не пометить их no-cache/private. Serverless-платформы: классическая AWS Lambda за API Gateway буферизовала весь ответ by design — стримингу нужна явно стриминго-способная инфраструктура (Lambda response streaming или edge/Node-серверы, которые flush-ат). Диагностика, разрезающая всё это: curl -N прямо в приложение (стримит? ваш код в порядке), затем в каждый слой наружу, пока стрим не перестанет стримить, — этот хоп и есть виновник.