Server-Sent Events

// We want to listen to events for a specific chat...
const EVENT_SOURCE_URL = 'https://sse.example.com/chats/123/event-source';

// ...so we register an EventSource for it.
let eventSource = new EventSource(EVENT_SOURCE_URL);

// When the connection is opened
eventSource.addEventListener('open', (e) => {
  console.log(`EventSource connection opened for ${EVENT_SOURCE_URL}`);
});

// When the connection encounters an error
eventSource.addEventListener('error', (e) => {
  console.log(`Error for ${EVENT_SOURCE_URL}`, e);
});

// SSE connection streams can include named events.
// Here, we listen specifically for those named "chat-message"
eventSource.addEventListener('chat-message', (e) => {
  console.log(`Chat message received: ${e.data}`);
});

eventSource.close();

// Your normal HTTP server
Server server = Server.fromPort(8080);
// Special SSE-specific server
ServerSentEventServer sseServer = 
  ServerSentEventServer.fromPort(8081);

// Provide both servers to Soklet
SokletConfig config = SokletConfig.withServer(server)
  .serverSentEventServer(sseServer)
  .build();

// Soklet starts and manages both servers
try (Soklet soklet = Soklet.fromConfig(config)) {
  soklet.start();
  System.out.println("Soklet started, press [enter] to exit");
  soklet.awaitShutdown(ShutdownTrigger.ENTER_KEY);
}

public class ChatResource {
  // Use @ServerSentEventSource, not @GET.
  // Return type must be declared as HandshakeResult
  @ServerSentEventSource("/chats/{chatId}/event-source")
  public HandshakeResult chatEventSource(@PathParameter Long chatId) {
    // Accept the client handshake.
    // Soklet can now broadcast server-sent events to this client
    return HandshakeResult.accept();   
  }
}

@ServerSentEventSource("/chats/{chatId}/event-source")
public HandshakeResult chatEventSource(@PathParameter Long chatId) {
  // Declare some response headers
  Map<String, Set<String>> headers = Map.of(
    "X-Powered-By", Set.of("Soklet"),
    // Here we override a default header
    "X-Accel-Buffering", Set.of("yes")
  );

  // Declare a response cookie
  Set<ResponseCookie> cookies = Set.of(
    ResponseCookie.withName("lastRequest")
      .value(Instant.now().toString())
      .httpOnly(true)
      .secure(true)
      .maxAge(Duration.ofMinutes(5))
      .sameSite(SameSite.LAX)
      .build()
  );  

  // Supply to the "accepted" HandshakeResult builder
  return HandshakeResult.Accepted.builder()
    .headers(headers)
    .cookies(cookies)
    .build();
}

@ServerSentEventSource("/chats/{chatId}/event-source")
public HandshakeResult chatEventSource(@PathParameter Long chatId) {
  // Can specify whatever status/headers/cookies/body you like
  Response response = Response.withStatusCode(403)
    .body("You're not authorized")
    .build();

  // Goes through ResponseMarshaler::forResourceMethod, as normal
  return HandshakeResult.rejectWithResponse(response);
}

@ServerSentEventSource("/chats/{chatId}/event-source")
public HandshakeResult chatEventSource(@PathParameter Long chatId) {
  // Goes through ResponseMarshaler::forThrowable, as normal
  if(!userIsAuthorized(chatId))
    throw new ExampleException("You're not authorized");

  return HandshakeResult.accept();
}

// Get a reference to your SSE server...
ServerSentEventServer sseServer = ...;

// ...acquire a broadcaster for a specific resource path...
ResourcePath resourcePath =
  ResourcePath.fromPath("/chats/123/event-source");
ServerSentEventBroadcaster broadcaster = 
  sseServer.acquireBroadcaster(resourcePath).orElseThrow();

// ...construct the payload...
ServerSentEvent event = ServerSentEvent.withEvent("chat-message")
  .id(Instant.now().toString()) // any string you like
  .data("Hello, world") // often JSON
  .retry(Duration.ofSeconds(5))
  .build();

// ...and send it to all connected clients.
broadcaster.broadcastEvent(event);

// Acquire broadcaster as usual...
ResourcePath resourcePath =
  ResourcePath.fromPath("/chats/123/event-source");
ServerSentEventBroadcaster broadcaster = 
  sseServer.acquireBroadcaster(resourcePath).orElseThrow();

// ...and send a comment to all listeners on /chats/123/event-source.
// The below comment will write ": testing" to the socket
ServerSentEventComment comment = ServerSentEventComment.fromComment("testing");

broadcaster.broadcastComment(comment);

@ServerSentEventSource("/chats/{chatId}/event-source")
public HandshakeResult chatEventSource(
  @PathParameter Long chatId,
  Request request
) {
  // Ordered locales via Soklet's Accept-Language parsing
  List<Locale> locales = request.getLocales();
  Locale locale = locales.isEmpty()
    ? Locale.getDefault()
    : locales.get(0);

  // When accepting the handshake, store off the Locale on the connection.
  // The clientContext is of type Object, so use whatever value you like
  return HandshakeResult.Accepted.builder()
    .clientContext(locale)
    .build();
}

// Later, when broadcasting:
ServerSentEventBroadcaster broadcaster =
  sseServer.acquireBroadcaster(ResourcePath.fromPath("/chats/123/event-source")).orElseThrow();

// Group by Locale and memoize payloads per-locale
broadcaster.broadcastEvent(
  // First, turn the context into a key that represents a unique type of broadcast.
  // Here, it's just a broadcast per-Locale (e.g. US English and Brazilian Portuguese)
  // so we just return the Locale by casting our clientContext Object.
  // Real systems might specify a richer clientContext and map it to
  // a "key" type with Locale, ZoneId, user role, etc.
  (clientContext) -> (Locale) clientContext,
  // ...then, memoization guarantees we construct exactly 1 payload per-Locale
  (locale) -> ServerSentEvent.withEvent("chat-message")
    .data(exampleLocalizedMessageFor(locale))
    .build()
);

@ServerSentEventSource("/chats/{chatId}/event-source")
public HandshakeResult chatEventSource(
  @PathParameter Long chatId,
  // Browsers will send this header automatically on reconnects
  @RequestHeader(name="Last-Event-ID", optional=true) String lastEventId
) {
  Chat chat = myChatService.find(chatId);

  // Exceptions that bubble out will reject the handshake and go through the
  // ResponseMarshaler::forThrowable path, same as non-SSE Resource Methods
  if (chat == null)
    throw new NoSuchChatException();

  // If a Last-Event-ID header was sent, pull data to "catch up" the client
  List<ChatMessage> catchupMessages = new ArrayList<>();

  if(lastEventId != null)
    catchupMessages.addAll(myChatService.findCatchups(chatId, lastEventId));
  
  // Customize "accept" handshake with a client initializer
  return HandshakeResult.Accepted.builder()
    .clientInitializer((unicaster) -> {
      // Unicast "catchup" initialization events to this specific client.
      // The unicaster is guaranteed to write these events before any
      // other broadcaster does, allowing clients to safely catch up
      // without the risk of event interleaving
      catchupMessages.stream()
        .map(catchupMessage -> ServerSentEvent.withEvent("chat-message")
          .id(catchupMessage.id())
          .data(catchupMessage.toJson())
          .retry(Duration.ofSeconds(5))
          .build())
        .forEach(event -> unicaster.unicastEvent(event));
    })
    .build();
}

const EVENT_SOURCE_URL = 'https://sse.example.com/chats/123/event-source';

// URL and "withCredentials" are the only possible customizations
let eventSource = new EventSource(EVENT_SOURCE_URL, {
  withCredentials: true
});

// Make a call to your backend to get a signing token...
let signingToken = await obtainSigningToken();

// ...construct a URL with it...
let eventSourceUrl = 'https://sse.example.com/chats/123/event-source'
  + `?signingToken=${encodeURIComponent(signingToken)}`;

// ...and use the constructed URL to create the EventSource.
// Notice that we omit the less-secure "withCredentials: true" config
let eventSource = new EventSource(eventSourceUrl);

@ServerSentEventSource("/chats/{chatId}/event-source")
public HandshakeResult chatEventSource(
  @PathParameter Long chatId,
  // Require that clients specify a signing token
  @QueryParameter String signingToken
) {
  Chat chat = myChatService.find(chatId);

  // Exceptions that bubble out will reject the handshake and go through the
  // ResponseMarshaler.forThrowable(...) path, same as non-SSE Resource Methods
  if (chat == null)
    throw new ChatNotFoundException();

  // Perform cryptographic + expiry verification of the token here.
  // You might also mark it as "cannot be reused" in your database
  myAuthorizationService.verify(signingToken);

  // Accept the handshake with no additional data
  return HandshakeResult.accept();   
}

@ServerSentEventSource("/hello-world")
public HandshakeResult helloWorld() {
  // Immediately accept, no special behavior
  return HandshakeResult.accept();   
}

Server server = Server.fromPort(8080);
ServerSentEventServer sseServer = 
  ServerSentEventServer.fromPort(8081);

SokletConfig config = SokletConfig.withServer(server)
  .serverSentEventServer(sseServer)
  .build();

try (Soklet soklet = Soklet.fromConfig(config)) {
  soklet.start();
  System.out.println("Soklet started, press [enter] to exit");
  soklet.awaitShutdown(ShutdownTrigger.ENTER_KEY);
}

# Hold a socket open for GET /hello-world and wait for server-sent events.
# This is a bare-bones raw HTTP request: a method, a URL, and a single `Host` header.
echo -ne 'GET /hello-world HTTP/1.1\r\nHost: localhost\r\n\r\n' | netcat localhost 8081

HTTP/1.1 200 OK
Content-Type: text/event-stream; charset=UTF-8
Cache-Control: no-cache
Cache-Control: no-transform
Connection: keep-alive
Date: Sat, 18 Oct 2025 13:04:12 GMT
X-Accel-Buffering: no

:

ResourcePath resourcePath = ResourcePath.fromPath("/hello-world");
ServerSentEventBroadcaster broadcaster = 
  sseServer.acquireBroadcaster(resourcePath).orElseThrow();
 
ServerSentEvent event = ServerSentEvent.withEvent("hello")
  .data("testing\nmultiple\nlines")
  .id(Instant.now().toString())
  .retry(Duration.ofSeconds(5))
  .build();

broadcaster.broadcastEvent(event);

event: hello
id: 2025-10-18T13:04:46.750110Z
retry: 5000
data: testing
data: multiple
data: lines