9.10.0 - Soporte para respuestas HTTP por streaming

Osumi Framework 9.10.0

Osumi Framework 9.10.0 incorpora soporte nativo para respuestas HTTP por streaming, pensado para servir archivos grandes o contenido generado progresivamente sin cargar el cuerpo completo en memoria.

OStreamResponse

Se añade OStreamResponse, una nueva respuesta HTTP basada en un stream PHP legible.

Permite configurar:

• cabeceras HTTP;
• código de estado;
• tamaño de bloque de lectura;
• cierre automático del recurso.

Los streams administrados por el framework se cierran al finalizar, al descartarse la respuesta o al destruirse el objeto.

Componentes streaming

Los componentes pueden devolver directamente un OStreamResponse desde run():

public function run(): OStreamResponse

También se admiten las variantes con ORequest y DTO:

public function run(ORequest $req): OStreamResponse
public function run(MyDTO $dto): OStreamResponse

Cuando run() declara explícitamente OStreamResponse, el componente puede omitir su archivo de plantilla.

Una respuesta streaming no puede anidarse dentro de otro componente ni convertirse a string.

Integración con Middlewares

Las respuestas streaming mantienen el pipeline de Middlewares.

El flujo es:

before
↓
Componente
↓
OStreamResponse
↓
afterRender
↓
afterResponse
↓
Cierre de conexiones de base de datos
↓
Cabeceras HTTP
↓
Emisión del stream por bloques

No se envía ningún byte del stream hasta que afterRender y afterResponse han terminado.

Durante estas fases:

$data['is_streaming_response'] === true

Los Middlewares pueden modificar contexto, cabeceras y estado HTTP o detener la respuesta antes de comenzar la emisión.

No pueden sustituir body en una respuesta streaming, ya que no existe un cuerpo completo materializado en memoria.

Layouts

Los layouts se omiten automáticamente para respuestas OStreamResponse.

Las respuestas tradicionales basadas en plantillas mantienen exactamente el comportamiento anterior.

Gestión de recursos

La emisión se realiza por bloques, con un tamaño predeterminado de 1 MiB, evitando cargar archivos completos en memoria.

Antes de comenzar una descarga potencialmente larga, el framework libera las conexiones de base de datos que ya no son necesarias.

Si un Middleware detiene la petición antes de la emisión:

• el stream se descarta;
• no se envía ningún byte;
• se restauran las cabeceras normales;
• se genera la respuesta de error habitual.

También se han añadido validaciones para streams no legibles, cabeceras HTTP inválidas, códigos de estado y tamaños de bloque incorrectos.

Compatibilidad

9.10.0 es compatible hacia atrás con 9.9.1.

No requiere cambios en aplicaciones existentes y no añade ningún paso automático de migración.

Las respuestas tradicionales, componentes con plantilla, layouts y Middlewares existentes continúan funcionando sin cambios.

Documentación

La documentación se ha actualizado en:

• castellano;
• inglés;
• euskera;
• documentación específica para LLM;
• llms.txt;
• guía de migración 9.9.1 → 9.10.0.