Server-Sent Events (SSE)
Octopus proxies Server-Sent Events as a streaming response. Unlike the buffered HTTP path, the upstream's event stream is forwarded to the client incrementally, so events arrive as the upstream emits them.
Detection01
A request is handled as SSE when its Accept header contains text/event-stream. This
check runs before the body is buffered so the response can be streamed back.
How it is handled02
Route match. The upstream is selected by the normal router from the request host, method, and path.
Build the upstream request. The path is rewritten with the route's strip_prefix /
add_prefix, and the query string is preserved. The request body is read and forwarded,
so POST-based SSE works. A relevant set of headers is forwarded: Accept,
Last-Event-ID, Authorization, Cookie, Content-Type, Content-Length,
X-Forwarded-For / X-Forwarded-Proto / X-Forwarded-Host, X-Real-IP, Host,
User-Agent, and Cache-Control. If the client sent no Accept, the gateway adds
Accept: text/event-stream.
Connect with timeout. The gateway connects to the upstream with a 10-second connect timeout. The connection to the upstream is plaintext HTTP.
Stream the response. The upstream response body is streamed straight to the client —
no buffering. If the upstream did not set them, the gateway ensures
Content-Type: text/event-stream and Cache-Control: no-cache on the response.
Last-Event-ID is forwarded to the upstream, so clients that reconnect can resume from
where they left off — provided the upstream implements resume.
Example route03
SSE needs no special route — point a path at an upstream that emits an event stream:
upstreams:
- name: events-service
instances:
- id: events-1
host: 127.0.0.1
port: 8080
routes:
- path: /events
upstream: events-serviceThe client requests it with Accept: text/event-stream; the gateway does the rest. See
Routes and Routing.
The same upstream and route can serve normal JSON responses too — the gateway only
switches to the streaming SSE path when the client asks for text/event-stream.
Limitations04
Detection is purely
Accept-header based. An upstream that emitstext/event-streambut is requested without thatAcceptvalue will be proxied on the buffered HTTP path instead of the streaming path.The upstream connection on the SSE path is plaintext HTTP.
The gateway does not synthesize keepalive comments or
retry:directives itself; it forwards whatever the upstream sends.