http-event-stream

Stream real-time events over plain HTTP using Server Sent Events (SSE) in node.js.

Focusing on spec-compliant Server Sent Event streams, we not only stream events, but also replay past events on demand. Event replaying allows clients to disconnect and reconnect to a stream without missing any data.

📡  Server-sent events via plain HTTP
💡  Stream as a REST endpoint route
☁️  Immutable state allows cleaner code
🗺️  Framework-agnostic - works with Express, Koa & others
🛡️  No more "Failed to upgrade websocket connection"

Installation

npm install http-event-stream
# or
yarn add http-event-stream

Usage

Using Express.js

const express = require("express")

const app = express()

// Example event stream: Stream the current time
app.get("/time-stream", (req, res) => {
  // Find the implementation below
  streamSampleEvents(req, res)
})

app.listen(3000)

Using Koa.js

const Koa = require("koa")
const Router = require("koa-router")

const app = new Koa()
const router = new Router()

// Example event stream: Stream the current time
router.get("/time-stream", (context) => {
  // Find the implementation below
  streamSampleEvents(context.req, context.res)

  // Koa quirk: Don't close the request/stream after handling the route!
  context.respond = false
})

app
  .use(router.routes())
  .use(router.allowedMethods())
  .listen(3000)

Sample stream implementation

const { streamEvents } = require("http-event-stream")
const events = require("./some-event-emitter")

function streamSampleEvents (req, res) {
  const fetchEventsSince = async (lastEventId) => {
    return [ /* all events since event with ID `lastEventId` would go here */ ]
  }
  return streamEvents(req, res, {
    async fetch (lastEventId) {
      // This method is mandatory to replay missed events after a re-connect
      return fetchEventsSince(lastEventId)
    },
    stream (stream) {
      const listener = () => {
        stream.sendEvent({
          event: "time",
          data: JSON.stringify({
            now: new Date().toISOString()
          })
        })
      }

      // Subscribe to some sample event emitter
      events.addEventListener("data", listener)

      // Return an unsubscribe function, so the stream can be terminated properly
      const unsubscribe = () => events.removeEventListener("data", listener)
      return unsubscribe
    }
  })
}

A server-sent event sent via stream.sendEvent() or returned from fetch() has to have the following shape:

interface ServerSentEvent {
  data: string | string[]
  event?: string,
  id?: string
  retry?: number
}

Besides stream.sendEvent(event: ServerSentEvent) there is also stream.sendComment(comment: string) and stream.close().

See Using server-sent events - Fields.

API

See dist/index.d.ts.

Differences to WebSockets

Brief summary:

Automatic reconnecting out of the box
Unidirectional data flow
HTTP/2 multiplexing out of the box
No Connection: Upgrade - no special reverse proxy config

What do we use websockets for? Usually for streaming events from the server to client in realtime.

Server Sent Events (SSE) only do this one job, but do it really well. It's a simple protocol, using a normal HTTP connection, only streaming data from the server to the client.

You can pass parameters and headers from the client to the server when opening the stream, but the actual stream is read-only for the client.

It might sound like a strong limitation first, but actually it's a pretty clean approach: It makes the stream stateless and allows cool things like combining multiple streams into one which you could not easily do with a duplex stream.

Authentication

Since it's all just plain HTTP, we can use headers like we always do. Go ahead and use your favorite auth middleware that you use for the other REST endpoints.

Client

Make sure to include a polyfill in your web page code, since not all major browsers provide native support for SSE.

Try event-source-polyfill.

To connect to SSE streams from node.js, use the eventsource package.

License

MIT

andywer/http-event-stream