feat: SSE handler, send y keepalive (issue 0011 fase 2)

2026-04-18 17:25:03 +02:00
parent 0255207514
commit 637bc8fd34
7 changed files with 546 additions and 0 deletions
@@ -0,0 +1,49 @@
+---
+name: sse_send
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func SSESend(w http.ResponseWriter, event SSEEvent) error"
+description: "Escribe un evento Server-Sent Events formateado al ResponseWriter segun la spec W3C y hace flush si el writer implementa http.Flusher. Campos opcionales (event, id, retry) solo se incluyen si tienen valor. Data con saltos de linea se traduce a multiples lineas data: segun la spec."
+tags: [sse, server-sent-events, http, server, infra, realtime]
+uses_functions: []
+uses_types: [SSEEvent_go_infra]
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [fmt, net/http, strings]
+params:
+  - name: w
+    desc: "http.ResponseWriter destino. Debe tener headers SSE ya seteados (Content-Type: text/event-stream). Si implementa http.Flusher se hace flush tras la escritura."
+  - name: event
+    desc: "SSEEvent a serializar. Campos opcionales se omiten si estan vacios. Data multilinea se trocea en varias lineas data: segun la spec."
+output: "error si la escritura al ResponseWriter falla, nil si el evento se envio y se hizo flush correctamente"
+tested: true
+tests: ["serializa data simple sin event ni id", "incluye event cuando esta presente", "incluye id cuando esta presente", "incluye retry cuando es positivo", "data multilinea genera multiples lineas data:", "hace flush si el writer es Flusher"]
+test_file_path: "functions/infra/sse_test.go"
+file_path: "functions/infra/sse_send.go"
+---
+
+## Ejemplo
+
+```go
+http.HandleFunc("/events", func(w http.ResponseWriter, r *http.Request) {
+    w.Header().Set("Content-Type", "text/event-stream")
+    w.Header().Set("Cache-Control", "no-cache")
+    w.Header().Set("Connection", "keep-alive")
+
+    SSESend(w, SSEEvent{
+        Event: "metric",
+        ID:    "1",
+        Data:  `{"cpu": 45.2}`,
+    })
+})
+```
+
+## Notas
+
+Funcion atomica: solo formatea y flushea un evento. La gestion del ciclo de vida (headers, loop de eventos, deteccion de desconexion) se hace en `sse_handler`.
+
+Sigue estrictamente la spec W3C de Server-Sent Events. El doble salto de linea final separa eventos. Para enviar un comentario keepalive (no un evento) escribir `: keepalive\n\n` directamente — no usar esta funcion.