Adds support for multi-line SSE event (helidon-io#10406)

* Adds support for multi-line SSE events. These are concatenated using '\n' on the client side and reported as a single event. New builder method to pass an array of strings for a multi-line event. Adds support to request data of an event as a String[].

Author: spericas

http/sse/src/main/java/io/helidon/http/sse/SseEvent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2025 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -125,6 +125,9 @@ public <T> T data(Class<T> clazz, MediaType mediaType) {
         if (clazz.equals(byte[].class)) {
             return (T) sdata.getBytes(StandardCharsets.UTF_8);
         }
+        if (clazz.equals(String[].class)) {
+            return (T) sdata.split("\n");
+        }
         try {
             if (mediaContext == null) {
                 throw new IllegalStateException("Media context has not been set on this event");
@@ -294,7 +297,40 @@ public Builder mediaType(MediaType mediaType) {
          */
         public Builder data(Object data) {
             Objects.requireNonNull(data);
-            this.data = data;
+            // not set or an override?
+            if (this.data == NO_DATA || !(this.data instanceof String)) {
+                this.data = data;
+            } else {
+                // handle multi-line data
+                if (!(data instanceof String)) {
+                    throw new IllegalArgumentException("Cannot concatenate non-string event data");
+                }
+                this.data += "\n" + data;    // concatenate strings
+            }
+            return this;
+        }
+
+        /**
+         * Use an array of strings to set the value of a multi-line event.
+         *
+         * @param data array of strings
+         * @return updated builder instance
+         */
+        public Builder data(String... data) {
+            StringBuilder builder = new StringBuilder();
+            if (this.data != NO_DATA) {
+                if (!(this.data instanceof String)) {
+                    throw new IllegalArgumentException("Cannot concatenate non-string event data");
+                }
+                builder.append(this.data).append("\n");
+            }
+            for (int i = 0; i < data.length; i++) {
+                builder.append(data[i]);
+                if (i != data.length - 1) {
+                    builder.append("\n");
+                }
+            }
+            this.data = builder.toString();
             return this;
         }
 

webclient/sse/src/main/java/io/helidon/webclient/sse/SseSourceHandlerProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2025 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -79,6 +79,9 @@ public <X extends Source<SseEvent>> void handle(X source, HttpClientResponse res
                 }
                 emit = true;
                 if (line.startsWith(DATA)) {
+                    if (!data.isEmpty()) {
+                        data.append("\n");      // multi-line string data
+                    }
                     data.append(skipPrefix(line));
                 } else if (line.startsWith(EVENT)) {
                     sseBuilder.name(skipPrefix(line));

webserver/sse/src/main/java/io/helidon/webserver/sse/DataWriterSseSink.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024 Oracle and/or its affiliates.
+ * Copyright (c) 2024, 2025 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -100,10 +100,23 @@ public DataWriterSseSink emit(SseEvent sseEvent) {
         }
         Object data = sseEvent.data();
         if (data != null) {
-            bufferData.write(SSE_DATA);
-            byte[] bytes = serializeData(data, sseEvent.mediaType().orElse(MediaTypes.TEXT_PLAIN));
-            bufferData.write(bytes);
-            bufferData.write(SSE_NL);
+            MediaType mediaType = sseEvent.mediaType().orElse(MediaTypes.TEXT_PLAIN);
+
+            // is it multi-line string data?
+            if (data instanceof String stringData && stringData.contains("\n")) {
+                String[] lines = stringData.split("\n");
+                for (String line : lines) {
+                    bufferData.write(SSE_DATA);
+                    byte[] bytes = serializeData(line, mediaType);
+                    bufferData.write(bytes);
+                    bufferData.write(SSE_NL);
+                }
+            } else {
+                bufferData.write(SSE_DATA);
+                byte[] bytes = serializeData(data, mediaType);
+                bufferData.write(bytes);
+                bufferData.write(SSE_NL);
+            }
         }
         bufferData.write(SSE_NL);
 

webserver/tests/sse/src/test/java/io/helidon/webserver/tests/sse/SseClientTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2025 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -53,6 +53,7 @@ class SseClientTest extends SseBaseTest {
     @SetUpRoute
     static void routing(HttpRules rules) {
         rules.get("/sseString1", SseClientTest::sseString1);
+        rules.get("/sseString2", SseClientTest::sseString2);
         rules.get("/sseJson1", SseClientTest::sseJson1);
         rules.get("/sseJson2", SseServerTest::sseJson2);
     }
@@ -71,6 +72,20 @@ static void sseString1(ServerRequest req, ServerResponse res) {
         }
     }
 
+    static void sseString2(ServerRequest req, ServerResponse res) {
+        try (SseSink sseSink = res.sink(SseSink.TYPE)) {
+            sseSink.emit(SseEvent.builder()
+                                 .data("first line")
+                                 .data("second line")
+                                 .data("third line")
+                                 .build())
+                    .emit(SseEvent.builder()
+                                  .name("second")
+                                  .data("first line\nsecond line\nthird line")
+                                  .build());
+        }
+    }
+
     @Test
     void testSseString1() throws InterruptedException {
         try (Http1ClientResponse r = client.get("/sseString1").header(ACCEPT_EVENT_STREAM).request()) {
@@ -106,6 +121,26 @@ public void onClose() {
         }
     }
 
+    @Test
+    void testSseString2() throws InterruptedException {
+        try (Http1ClientResponse r = client.get("/sseString2").header(ACCEPT_EVENT_STREAM).request()) {
+            CountDownLatch latch = new CountDownLatch(1);
+            r.source(SseSource.TYPE, new SseSource() {
+
+                @Override
+                public void onEvent(SseEvent event) {
+                    assertThat(event.data(), is("first line\nsecond line\nthird line"));
+                }
+
+                @Override
+                public void onClose() {
+                    latch.countDown();
+                }
+            });
+            assertThat(latch.await(5, TimeUnit.SECONDS), is(true));
+        }
+    }
+
     @Test
     void testSseJson1() throws InterruptedException {
         try (Http1ClientResponse r = client.get("/sseJson1").header(ACCEPT_EVENT_STREAM).request()) {

webserver/tests/sse/src/test/java/io/helidon/webserver/tests/sse/SseEventTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2025 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -106,4 +106,47 @@ void testConvertNoData() {
         assertThrows(IllegalStateException.class, () -> event.data(Object.class));
         assertThrows(IllegalStateException.class, () -> event.data(Object.class, MediaTypes.TEXT_PLAIN));
     }
+
+    @Test
+    void testMultiLineStringData() {
+        SseEvent event = SseEvent.builder()
+                .mediaContext(mediaContext)
+                .data("first")
+                .data("second")
+                .data("third")
+                .build();
+        assertThat(event.data(String.class), is("first\nsecond\nthird"));
+    }
+
+    @Test
+    void testBadMultiLineStringData() {
+        assertThrows(IllegalArgumentException.class,
+                     () -> SseEvent.builder()
+                             .mediaContext(mediaContext)
+                             .data("first")
+                             .data(new Object())    // not a string!
+                             .data("third")
+                             .build());
+    }
+
+    @Test
+    void testMultiLineStringArrayData() {
+        SseEvent event = SseEvent.builder()
+                .mediaContext(mediaContext)
+                .data("first", "second", "third")
+                .build();
+        assertThat(event.data(String.class), is("first\nsecond\nthird"));
+        assertThat(event.data(String[].class), is(new String[]{"first", "second", "third"}));
+    }
+
+    @Test
+    void testBadMultiLineStringArrayData() {
+        assertThrows(IllegalArgumentException.class,
+                     () -> SseEvent.builder()
+                             .mediaContext(mediaContext)
+                             .data(new Object())
+                             .data("first", "second", "third")      // cannot concatenate
+                             .build());
+    }
+
 }