Sse Stream

Okapi SSE (Server-Sent Events) Skills

Okapi provides built-in SSE support for real-time server-to-client streaming over HTTP. SSE connections are long-lived GET requests where the server pushes events using the text/event-stream content type. The framework handles headers, flushing, keep-alive pings, and serialization automatically.

Core Types

| Type | Description | |------|-------------| | Message | Single SSE message with ID, Event, Data, Retry, Serializer fields | | StreamOptions | Advanced stream config: Serializer, PingInterval, OnError callback | | Serializer | Interface: Serialize(data any) (string, error) — custom data encoding | | SendFunc | func(data any, eventType string) (string, error) |

Built-in Serializers

| Serializer | Description | |------------|-------------| | okapi.JSONSerializer | Default — marshals data as JSON | | okapi.TextSerializer | Plain text via fmt.Sprintf("%v", data) | | okapi.Base64Serializer | Base64-encodes []byte data |

Sending Single Events

// Fire-and-forget event (no ID, auto-generated internally)
c.SSEvent("message", data)

// Event with explicit ID
c.SSESendEvent("event-1", "message", data)

// Data-only (no event type)
c.SSESendData(data)

// Explicit serializer variants
c.SSESendJSON(data)            // JSON serializer
c.SSESendText("hello")         // Text serializer
c.SSESendBinary([]byte{...})   // Base64 serializer
c.SendSSECustom(data, mySerializer)  // Custom serializer

> c.SendSSEvent(id, eventType, data) is deprecated — use c.SSESendEvent(...).

Each helper writes the frame and flushes it, so events reach the client immediately. okapi.LoggerMiddleware skips SSE requests, keeping long-lived streams out of the access log.

A Message can also be written directly to any http.ResponseWriter:

msg := okapi.Message{Event: "update", Data: payload}
id, err := msg.Send(c.Response())   // writes the frame, returns the message ID
err = msg.Close(c.Response())       // flush

Simple Event Loop (Recommended for Most Cases)

The simplest pattern — use a ticker and send events directly in a loop:

app.Get("/events", func(c *okapi.Context) error {
    ticker := time.NewTicker(1 * time.Second)
    defer ticker.Stop()

    ctx := c.Request().Context()
    for {
        select {
        case  {
    const data = JSON.parse(event.data);
    console.log(data);
});

// Handle errors and reconnect
eventSource.onerror = () => {
    eventSource.close();
    setTimeout(() => { /* reconnect */ }, 3000);
};

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jkaninda
• Source: jkaninda/okapi-skills
• License: MIT

Install and usage instructions live in the source repository linked above.