- status long-running quote calculation
- progress import/export catalog
- notification order status
- background job progress
- async validation result
- workflow task update
- user-facing dashboard refresh
- operational event feed

Do not introduce long-lived connections before proving that polling, eventing, or async callback cannot satisfy the requirement.

- one-way vs bidirectional communication
- browser vs service client
- connection duration
- event volume
- latency expectation
- network intermediaries
- retry/resume requirement
- tenant isolation
- authentication model
- gateway/proxy capability
- operational maturity

Prefer the simplest pattern that satisfies latency and interaction requirements.

1. normal polling with sane cache/status endpoint
2. long polling for wait-until-change semantics
3. SSE for one-way UI event feed
4. WebSocket only for true bidirectional realtime interaction

GET /quotes/{quoteId}/calculation-status
Accept: application/json

{
  "quoteId": "q-123",
  "status": "IN_PROGRESS",
  "progressPercent": 70,
  "lastUpdatedAt": "2026-07-10T02:00:00Z",
  "nextRecommendedPollAfterMs": 3000
}

- easy to cache or throttle
- easy to secure
- easy to observe
- easy to retry
- easy to load test
- compatible with API gateway
- no sticky connection requirement

- server-suggested polling interval
- ETag / conditional request
- rate limiting
- exponential backoff on unchanged response
- status resource with lightweight DB/cache query
- avoid recalculating expensive state per poll

- a change is available
- timeout expires
- client disconnects
- server cancels the wait
- service is shutting down

204 No Content
Retry-After: 3

200 OK
Content-Type: application/json

{
  "events": [],
  "nextCursor": "42",
  "retryAfterMs": 3000
}

- max wait duration
- max concurrent waits per user/tenant
- max global open waits
- max events returned per request
- cursor/offset semantics
- client retry interval
- timeout response semantics
- cancellation behavior
- shutdown behavior

@GET
@Path("/jobs/{id}/wait")
public Response waitForever(@PathParam("id") String id) throws InterruptedException {
    while (!jobDone(id)) {
        Thread.sleep(1000);
    }
    return Response.ok(loadResult(id)).build();
}

- blocks request thread
- unclear max wait
- no cancellation check
- no client disconnect awareness
- no concurrency cap
- no tenant-level fairness
- polling DB repeatedly
- painful shutdown

Long polling is a bounded wait on a notification mechanism, not a while-loop inside resource method.

@GET
@Path("/jobs/{jobId}/events")
@Produces(MediaType.APPLICATION_JSON)
public void waitForJobEvent(
        @PathParam("jobId") String jobId,
        @QueryParam("since") String cursor,
        @Suspended AsyncResponse asyncResponse) {

    asyncResponse.setTimeout(25, TimeUnit.SECONDS);
    asyncResponse.setTimeoutHandler(ar ->
        ar.resume(Response.status(Response.Status.NO_CONTENT)
            .header("Retry-After", "3")
            .build())
    );

    waitRegistry.register(jobId, cursor, new WaitCallback() {
        @Override
        public void onEvent(JobEventBatch events) {
            asyncResponse.resume(Response.ok(events).build());
        }

        @Override
        public void onFailure(Throwable error) {
            asyncResponse.resume(error);
        }
    });
}

- who owns waitRegistry memory?
- how is wait removed on timeout?
- how is wait removed on client disconnect?
- how is tenant quota enforced?
- what happens on service shutdown?
- does context propagate into callback?
- does callback run on a safe executor?

- server-to-client only
- text/event-stream content type
- usually browser-friendly
- built on HTTP
- reconnectable by client
- simpler than WebSocket for one-way events

id: 1001
event: quote-calculation-progress
data: {"quoteId":"q-123","progress":70}

const source = new EventSource('/api/quotes/q-123/events');

source.addEventListener('quote-calculation-progress', event => {
  const payload = JSON.parse(event.data);
  console.log(payload.progress);
});

source.onerror = error => {
  console.error('SSE disconnected', error);
};

@GET
@Path("/quotes/{quoteId}/events")
@Produces(MediaType.SERVER_SENT_EVENTS)
public void streamQuoteEvents(
        @PathParam("quoteId") String quoteId,
        @Context Sse sse,
        @Context SseEventSink sink) {

    eventSubscriptionService.subscribe(quoteId, event -> {
        OutboundSseEvent sseEvent = sse.newEventBuilder()
            .id(event.sequence())
            .name("quote-calculation-progress")
            .mediaType(MediaType.APPLICATION_JSON_TYPE)
            .data(event.payload())
            .build();

        sink.send(sseEvent);
    });
}

- sink lifecycle
- sink.close()
- error callback
- client disconnect
- heartbeat event
- subscription cleanup
- authentication expiry
- tenant quota
- event replay/resume
- backpressure / slow consumer

1. server sends events with monotonically increasing id
2. connection drops
3. browser reconnects and sends Last-Event-ID
4. server resumes after last delivered id if event history is available

Is the SSE stream ephemeral or replayable?

- simpler
- events lost on disconnect
- acceptable for low-value UI hints
- not acceptable for critical state transitions

- needs event store, cursor, or durable source
- more operationally complex
- required when client must not miss transitions

: heartbeat

event: heartbeat
data: {}

client <-> gateway <-> ingress <-> service <-> runtime

- API gateway idle timeout
- ingress idle timeout
- load balancer idle timeout
- servlet connector timeout
- application stream timeout

- gateway buffers text/event-stream and events arrive late
- proxy closes idle connection
- no heartbeat
- sink not closed after disconnect
- subscription leak
- user opens many browser tabs
- tenant-level fanout overload
- slow client blocks event delivery
- auth token expires mid-stream
- event ID not monotonic
- replay cursor not durable
- deployment kills active streams

- increasing open connection count
- heap growth from subscription objects
- stale user session subscriptions
- high thread count
- client reconnect storm
- duplicate events after reconnect
- missing events after reconnect
- noisy error logs during deployment

- active SSE connections
- SSE connections per tenant/user
- event send latency
- send failure count
- reconnect count
- subscription cleanup count
- heartbeat sent count
- stream duration histogram
- dropped event count

- server and client both send messages frequently
- latency matters
- message exchange is interactive
- one request/one response is not enough

- collaborative editing
- bidirectional control channel
- interactive operational console
- chat-like interface
- live negotiation session

@ServerEndpoint("/ws/quotes/{quoteId}")
public class QuoteWebSocketEndpoint {

    @OnOpen
    public void onOpen(Session session, @PathParam("quoteId") String quoteId) {
        // authenticate, authorize, register session
    }

    @OnMessage
    public void onMessage(String message, Session session) {
        // parse command, validate, dispatch
    }

    @OnClose
    public void onClose(Session session) {
        // unregister, cleanup
    }

    @OnError
    public void onError(Session session, Throwable error) {
        // log, cleanup, metrics
    }
}

Do not assume JAX-RS filters, exception mappers, or resource lifecycle apply automatically to WebSocket endpoints.

- long-lived sessions
- stateful connection registry
- heartbeat/ping-pong
- message framing
- backpressure per session
- horizontal scaling complexity
- sticky session or external pub/sub
- load balancer WebSocket support
- deployment drain behavior
- auth/session renewal

- container-level auth
- compression
- CORS
- request size limit
- raw access logging
- security headers

- resource-level auth
- correlation ID
- API logging
- tenant resolution
- request/response mutation

- servlet filter must not buffer stream unexpectedly
- compression filter may buffer or delay events
- timeout at connector may kill stream
- async-supported setting may matter

one open connection = one blocked request thread for minutes

one open connection = registered async continuation + bounded event callback

- connection objects
- subscriptions
- buffers
- event queues
- callback executor
- authentication/session state
- metrics/tracing context

What resource grows linearly with number of connected clients?

- server produces events faster than client reads
- buffer grows per connection
- event delivery blocks callback thread
- one tenant/user consumes unfair resources
- reconnect storm amplifies backlog

- bounded per-connection queue
- drop non-critical events
- coalesce progress updates
- disconnect slow consumer
- send latest state instead of every state transition
- require cursor-based catch-up through normal API
- tenant/user quota

Do not send progress 1%, 2%, 3%, ... if only latest progress matters.

- When is token validated?
- What happens when token expires while stream is open?
- Is authorization checked only on connect or per event?
- Can user permission change while connection is active?
- How is tenant resolved?
- Is tenant/user included in log and metric labels safely?

- user loses permission but stream remains open
- token expires but socket continues
- connection registered under wrong tenant
- event fanout leaks cross-tenant data
- WebSocket endpoint bypasses JAX-RS auth filter

- validate at connection/open request
- bind connection to user + tenant + permission snapshot
- periodically revalidate for long sessions if required
- close stream on auth/session expiry
- never route event by client-supplied tenant alone
- include authorization in subscription registration

- active connections by endpoint
- active connections by tenant tier, not raw tenant ID if high-cardinality risk
- connection duration histogram
- connect/disconnect count
- abnormal close count
- timeout count
- send error count
- dropped/coalesced event count
- reconnect rate
- slow consumer disconnect count

- stream opened
- stream closed with reason
- auth/authorization failure
- subscription cleanup failure
- unexpected send failure
- quota rejection

- every heartbeat
- every high-frequency event payload
- raw PII
- tenant/customer ID as unbounded metric label

Long-lived streams do not map cleanly to one trace span per connection if duration is huge.

- short span for connection setup
- metrics for connection lifetime
- sampled logs for abnormal events
- separate spans for backend event production

- pod receives SIGTERM
- Kubernetes removes pod from endpoints after readiness fails
- existing connections may continue until termination grace period
- active SSE/WebSocket clients disconnect
- clients reconnect to other pod

- readiness should fail before shutdown work starts
- connection registry should stop accepting new streams
- existing streams should be closed gracefully
- clients should reconnect safely
- event cursor should support resume when needed
- shutdown should not wait forever

- reconnect with backoff
- use last event ID or cursor
- handle duplicate events
- handle 401/403 by re-authentication
- handle 503 by retrying later

- Does API gateway support SSE?
- Does API gateway buffer streaming response?
- Does ingress support WebSocket upgrade?
- What is idle timeout?
- What is max connection duration?
- Are keepalive/heartbeat frames passed through?
- Is compression enabled, and does it buffer?
- Is sticky session required?
- Does WAF inspect or block upgrade/streaming?

- events arrive in batch, not real-time
- connection closes exactly after N seconds
- WebSocket handshake fails at gateway
- SSE works locally but fails in cluster
- browser reconnects continuously
- stream endpoint works with curl but not behind APIM/API Gateway

- Is the service running in Servlet container, Jersey standalone, GlassFish, Grizzly, Tomcat, Jetty, or another runtime?
- Does the runtime support async JAX-RS properly?
- Does the runtime support SSE API used by the code?
- Is WebSocket handled by Jakarta WebSocket, container-specific API, or separate gateway/platform?
- Are streaming endpoints covered by the same filters as normal REST endpoints?

- Does API gateway support SSE?
- Does it buffer streaming response?
- Does it support WebSocket upgrade?
- What are idle timeout and max connection duration?
- Are timeout values documented in platform standards?
- Is sticky session enabled or required?
- Is compression disabled for SSE if needed?

- How is user identity resolved?
- How is tenant resolved?
- Is authorization checked at subscription time?
- What happens when token expires?
- Can permissions change while stream is open?
- Are WebSocket endpoints covered by equivalent auth logic?
- Are tenant/customer IDs safely handled in logs and metrics?

- Max active connections per pod?
- Max active connections per tenant/user?
- Memory per connection estimate?
- Queue size per connection?
- Callback executor size?
- Slow consumer policy?
- Shutdown drain policy?

- Active connection metrics?
- Reconnect rate?
- Abnormal close count?
- Event send latency?
- Dropped/coalesced events?
- Subscription cleanup failure?
- Heartbeat count?
- Dashboards and alerts?

- Are events ephemeral or replayable?
- Is there a cursor or event ID?
- What is duplicate handling policy?
- What is missing event recovery path?
- Is critical business state available through normal API/database/event log?

[ ] Why is normal polling insufficient?
[ ] Is the selected pattern the simplest one that satisfies the requirement?
[ ] Is max connection duration explicit?
[ ] Is timeout behavior explicit?
[ ] Is client retry/backoff behavior documented?
[ ] Is authentication handled?
[ ] Is authorization handled?
[ ] Is tenant isolation handled?
[ ] Is per-user/per-tenant quota enforced?
[ ] Are connection resources bounded?
[ ] Are queues bounded?
[ ] Is slow consumer behavior defined?
[ ] Is cleanup guaranteed on close/error/timeout?
[ ] Is deployment drain behavior safe?
[ ] Are gateway/LB timeout assumptions verified?
[ ] Are metrics/logs added?
[ ] Is high-cardinality metric risk avoided?
[ ] Are duplicate/missing events handled?
[ ] Are tests covering timeout, disconnect, and authorization failure?

- while loop inside resource method waiting for state
- no timeout
- no cleanup callback
- no quota
- no gateway verification
- no reconnect/backoff design
- no tenant isolation test
- WebSocket used for simple status polling
- business correctness depends on ephemeral connection delivery

- Use normal REST endpoint as source of truth for status/result.
- Use polling or long polling for simple waiting.
- Use SSE for UI progress/notification when one-way updates materially improve UX.
- Use Kafka/RabbitMQ for backend event propagation.
- Use WebSocket only for true bidirectional realtime interaction.

quote/order status -> database / domain state
progress events -> optional stream/feed
backend integration -> durable event bus
UI convenience -> polling/SSE/WebSocket

- Long-lived communication changes runtime and operational assumptions.
- Long polling is bounded waiting, not sleeping request threads.
- SSE is good for one-way event streams, especially browser clients.
- WebSocket is powerful but operationally expensive.
- Gateway, proxy, and load balancer behavior can make or break streaming patterns.
- Every long-lived connection requires explicit timeout, cleanup, quota, auth, and observability.
- Critical business state must not depend only on ephemeral connection delivery.