SSE

Planned APIs: This page documents the final SSE workflow. commflow@0.0.2 does not export an SSE runtime; do not use its imports as current production imports. See Current Release Quick Start for runnable exports.

When To Use It

SSE fits server-to-client event delivery:

Scenario	Fit
Notifications, state updates, job progress	Yes
Server-to-client one-way event streams	Yes
HTTP streaming works better through browsers or gateways	Yes
Client also needs to send continuous messages	Use Socket
One-shot request/response	Use Request

Create An SSE Client

import { createCommflowSseClient } from 'commflow';

const sse = createCommflowSseClient({
  baseURL: 'https://events.example.com',
  reconnect: {
    attempts: 5,
    delay: 1000
  }
});

Option	User meaning
`baseURL`	Event service URL.
`reconnect.attempts`	Maximum reconnect attempts after disconnect.
`reconnect.delay`	Base reconnect delay.

const stream = sse.subscribe('/notifications', {
  onMessage(event) {
    console.log(event.type, event.data);
  },
  onError(error) {
    console.error('sse failed', error);
  }
});

The returned stream must expose a close operation so users can release the connection on unmount, service shutdown, or task completion.

Handle Event Types

const stream = sse.subscribe('/jobs/42/events', {
  onMessage(event) {
    if (event.type === 'job.progress') {
      updateProgress(event.data.percent);
    }

    if (event.type === 'job.done') {
      markDone(event.data.result);
    }
  }
});

Prefer structured event types instead of treating every event as an untyped string.

Auth And Last-Event-ID

const stream = sse.subscribe('/jobs/42/events', {
  headers: {
    authorization: `Bearer ${token}`
  },
  lastEventId: resumeFromLastSeenId(),
  onMessage(event) {
    rememberLastSeenId(event.id);
  }
});

Field	Target behavior
`headers`	Send auth, tenant, or trace headers when connecting.
`lastEventId`	Resume from the last consumed event after disconnect.
`event.id`	Store it in business state or at least the current session.
`onMessage`	Message handling failure should enter an observable error path.

Reconnect Policy

An SSE disconnect is not always business failure; it may be a short network interruption.

Scenario	Guidance
Short network break	Reconnect automatically.
Auth expiry	Surface to business code, refresh token, then resubscribe.
Non-recoverable server error	Stop reconnecting and notify the user.
Page or task ended	Close manually and do not reconnect.

State model:

State	Meaning
`connecting`	Establishing the HTTP event stream.
`open`	Connected and receiving events.
`reconnecting`	Waiting for the next connection after a non-manual close.
`closed`	User closed it or the task ended.
`failed`	Reconnect exhausted or a non-recoverable error occurred.

Close And Cleanup

await stream.close();

Always release the stream when:

a frontend component unmounts;
a server request lifecycle ends;
user switches tenant, project, or topic;
a task completes and progress events are no longer needed.

Error Handling

SSE errors should be distinguishable:

Error	Handling
Network disconnect	Reconnect by retry policy.
Server rejection	Surface to business code.
Message parse failure	Record raw message and topic for diagnostics.
Retry exhausted	Enter final failed state.

See Errors And Retries for the broader error model.

When Not To Use SSE

If you need continuous client-to-server messages, rooms, binary data, or strongly interactive realtime channels, use Socket instead of emulating a duplex protocol with SSE.

#SSE

#When To Use It

#Create An SSE Client

#Subscribe To Events

#Handle Event Types

#Auth And Last-Event-ID

#Reconnect Policy

#Close And Cleanup

#Error Handling

#When Not To Use SSE

SSE