koapp-sse

@axiosleo/koapp Server-Sent Events Middleware

Source: src/middlewares/sse.js.

KoaSSEMiddleware upgrades a Koa request to a Server-Sent Events (SSE) stream, setting the right headers and exposing ctx.sse.send(...) for pushing events to the browser over plain HTTP.

Use SSE when:

• You need server → client streaming (notifications, logs, live charts)
• You do NOT need client → server streaming (use koapp-apps WebSocket instead)
• You want a simple, proxy-friendly transport - SSE works over HTTP/1.1

Browsers reconnect automatically; most reverse proxies handle it fine.

Import

const { KoaSSEMiddleware } = require('@axiosleo/koapp').middlewares;

Middleware factory

const middleware = KoaSSEMiddleware({
  pingInterval: 60000,  // ms between heartbeat comments (default 60s)
  closeEvent: 'close'   // event name sent on stream close
});

The factory returns a standard Koa middleware (ctx, next) => {}.

Wiring into a router handler

Because the framework already dispatches routes via its workflow, invoke the middleware inside the handler, passing context.koa:

const { Router } = require('@axiosleo/koapp');
const { KoaSSEMiddleware } = require('@axiosleo/koapp').middlewares;

const router = new Router('/');

router.any('/sse', async (context) => {
  const sse = KoaSSEMiddleware();
  await sse(context.koa, async () => {});

  context.koa.sse.send({ data: 'hello, world!' });

  process.nextTick(async () => {
    for (let i = 0; i < 5; i++) {
      context.koa.sse.send({ id: i, event: 'tick', data: { i } });
      await new Promise((r) => setTimeout(r, 1000));
    }
    context.koa.sse.close();
  });
});

Key points:

1. Call await sse(context.koa, async () => {}) - pass a no-op next.
2. After that, context.koa.sse exists.
3. Push events with context.koa.sse.send(event); end with .close().
4. Do not call success / failed / result in the same handler - SSE takes over the response body.