Add readable single-line log text

Author: CoderYellow

README.md

@@ -56,7 +56,25 @@ GET /api/v1/yarn/applications/application_123_0001/logs?follow=true&logFiles=std
 Accept: text/event-stream
 ```
 
-Log event payloads use Base64 so offsets remain byte-accurate.
+Log events include both representations:
+
+- `data`: Base64 containing the exact bytes used by `offset`.
+- `text`: a convenient UTF-8 view with newlines, tabs, backslashes, and control
+  characters escaped so the value is printable on one line.
+
+For example, a log chunk containing two lines has a payload like:
+
+```json
+{
+  "type": "LOG",
+  "encoding": "BASE64",
+  "data": "Zmlyc3QKc2Vjb25kCg==",
+  "text": "first\\nsecond\\n"
+}
+```
+
+Use `data` for exact reconstruction because a byte chunk can split a multi-byte
+UTF-8 character; use `text` for terminals, dashboards, and diagnostics.
 
 ## WebSocket
 

core/src/main/kotlin/org/openprojectx/hadoop/yarn/log/api/YarnLogEvent.kt

@@ -21,7 +21,8 @@ enum class YarnLogSource {
 
 /**
  * Transport-neutral event used by both SSE and WebSocket endpoints.
- * [data] is Base64 when [encoding] is `BASE64`.
+ * [data] is Base64 when [encoding] is `BASE64`. [text] is a lossy UTF-8 convenience
+ * view with line breaks and control characters escaped onto one line.
  */
 data class YarnLogEvent(
     val type: YarnLogEventType,
@@ -36,6 +37,7 @@ data class YarnLogEvent(
     val generation: Long? = null,
     val encoding: String? = null,
     val data: String? = null,
+    val text: String? = null,
     val state: String? = null,
     val message: String? = null,
 )

core/src/main/kotlin/org/openprojectx/hadoop/yarn/log/api/engine/DefaultYarnLogStreamService.kt

@@ -198,6 +198,7 @@ class DefaultYarnLogStreamService(
                 generation = cursor.generation,
                 encoding = "BASE64",
                 data = Base64.getEncoder().encodeToString(bytes),
+                text = bytes.toSingleLineLogText(),
             ),
         )
     }
@@ -247,6 +248,7 @@ class DefaultYarnLogStreamService(
             source = YarnLogSource.AGGREGATED,
             encoding = "BASE64",
             data = Base64.getEncoder().encodeToString(bytes),
+            text = bytes.toSingleLineLogText(),
         )
     }
 
@@ -287,6 +289,7 @@ class DefaultYarnLogStreamService(
             generation: Long? = null,
             encoding: String? = null,
             data: String? = null,
+            text: String? = null,
             state: String? = null,
             message: String? = null,
         ) = YarnLogEvent(
@@ -301,6 +304,7 @@ class DefaultYarnLogStreamService(
             generation = generation,
             encoding = encoding,
             data = data,
+            text = text,
             state = state,
             message = message,
         )

core/src/main/kotlin/org/openprojectx/hadoop/yarn/log/api/engine/SingleLineLogText.kt

@@ -0,0 +1,25 @@
+package org.openprojectx.hadoop.yarn.log.api.engine
+
+internal fun ByteArray.toSingleLineLogText(): String = toString(Charsets.UTF_8).toSingleLineLogText()
+
+private fun String.toSingleLineLogText(): String = buildString(length) {
+    for (character in this@toSingleLineLogText) {
+        when (character) {
+            '\\' -> append("\\\\")
+            '\n' -> append("\\n")
+            '\r' -> append("\\r")
+            '\t' -> append("\\t")
+            '\b' -> append("\\b")
+            '\u000c' -> append("\\f")
+            '\u0085' -> append("\\u0085")
+            '\u2028' -> append("\\u2028")
+            '\u2029' -> append("\\u2029")
+            else -> if (character.code < 0x20 || character.code == 0x7f) {
+                append("\\u")
+                append(character.code.toString(16).padStart(4, '0'))
+            } else {
+                append(character)
+            }
+        }
+    }
+}

core/src/test/kotlin/org/openprojectx/hadoop/yarn/log/api/engine/SingleLineLogTextTest.kt

@@ -0,0 +1,23 @@
+package org.openprojectx.hadoop.yarn.log.api.engine
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class SingleLineLogTextTest {
+    @Test
+    fun `escapes line breaks tabs backslashes and controls`() {
+        val bytes = "first\r\nsecond\t\\literal\u0001\u007f".toByteArray()
+
+        assertEquals("first\\r\\nsecond\\t\\\\literal\\u0001\\u007f", bytes.toSingleLineLogText())
+    }
+
+    @Test
+    fun `keeps ordinary unicode readable`() {
+        assertEquals("任务完成 ✓", "任务完成 ✓".toByteArray().toSingleLineLogText())
+    }
+
+    @Test
+    fun `escapes unicode line separators`() {
+        assertEquals("one\\u0085two\\u2028three\\u2029four", "one\u0085two\u2028three\u2029four".toByteArray().toSingleLineLogText())
+    }
+}