Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

feat(avf): add datagram framing codec for udp-over-vsock

ExTve9ac0cc93130
diff --git a/app/src/main/java/com/excp/podroid/engine/avf/DatagramFraming.kt b/app/src/main/java/com/excp/podroid/engine/avf/DatagramFraming.kt
new file mode 100644
index 0000000..b554220
--- /dev/null
+++ b/app/src/main/java/com/excp/podroid/engine/avf/DatagramFraming.kt
@@ -0,0 +1,51 @@
+/*
+ * Podroid - Rootless Podman for Android
+ * Copyright (C) 2024-2026 Podroid contributors
+ *
+ * Length-prefixed framing for UDP datagrams tunneled over the AVF vsock stream.
+ * Each frame is [u16 big-endian length][payload]. Must stay byte-compatible with
+ * udp_relay() in build-rootfs/vsock-agent/podroid-vsock-agent.c. Pure (no
+ * android.*) so it unit-tests on the JVM.
+ */
+package com.excp.podroid.engine.avf
+
+import java.io.IOException
+import java.io.InputStream
+
+internal object DatagramFraming {
+ /** Max UDP payload that fits a u16 length prefix. */
+ const val MAX_PAYLOAD = 65535
+
+ /** Frames the first [length] bytes of [payload] as [u16 len][payload]. */
+ fun encode(payload: ByteArray, length: Int): ByteArray {
+ require(length in 0..MAX_PAYLOAD) { "datagram length $length out of range" }
+ require(length <= payload.size) { "length $length exceeds payload size ${payload.size}" }
+ val out = ByteArray(2 + length)
+ out[0] = ((length ushr 8) and 0xff).toByte()
+ out[1] = (length and 0xff).toByte()
+ System.arraycopy(payload, 0, out, 2, length)
+ return out
+ }
+
+ /**
+ * Reads exactly one framed datagram, blocking until the full frame arrives.
+ * Returns the payload, null on clean EOF at a frame boundary, or throws
+ * IOException on EOF mid-frame (truncated).
+ */
+ fun readFrame(input: InputStream): ByteArray? {
+ val hi = input.read()
+ if (hi < 0) return null
+ val lo = input.read()
+ if (lo < 0) throw IOException("EOF in frame length")
+ val len = (hi shl 8) or lo
+ // A zero-length datagram is valid UDP and intentionally round-trips as len=0.
+ val buf = ByteArray(len)
+ var off = 0
+ while (off < len) {
+ val n = input.read(buf, off, len - off)
+ if (n < 0) throw IOException("EOF in frame payload ($off/$len)")
+ off += n
+ }
+ return buf
+ }
+}
diff --git a/app/src/test/java/com/excp/podroid/engine/avf/DatagramFramingTest.kt b/app/src/test/java/com/excp/podroid/engine/avf/DatagramFramingTest.kt
new file mode 100644
index 0000000..81a313c
--- /dev/null
+++ b/app/src/test/java/com/excp/podroid/engine/avf/DatagramFramingTest.kt
@@ -0,0 +1,67 @@
+package com.excp.podroid.engine.avf
+
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+import java.io.ByteArrayInputStream
+import java.io.IOException
+import java.io.InputStream
+
+class DatagramFramingTest {
+
+ @Test fun encode_writes_big_endian_length_prefix() {
+ val out = DatagramFraming.encode(byteArrayOf(1, 2, 3), 3)
+ assertEquals(5, out.size)
+ assertEquals(0, out[0].toInt()) // len hi
+ assertEquals(3, out[1].toInt()) // len lo
+ assertArrayEquals(byteArrayOf(1, 2, 3), out.copyOfRange(2, 5))
+ }
+
+ @Test fun encode_decode_round_trip() {
+ val payload = ByteArray(300) { (it % 256).toByte() }
+ val framed = DatagramFraming.encode(payload, payload.size)
+ val got = DatagramFraming.readFrame(ByteArrayInputStream(framed))
+ assertArrayEquals(payload, got)
+ }
+
+ @Test fun readFrame_reassembles_across_one_byte_reads() {
+ val payload = byteArrayOf(9, 8, 7, 6, 5)
+ val framed = DatagramFraming.encode(payload, payload.size)
+ // Stream that hands out exactly one byte per read() call.
+ val drip = object : InputStream() {
+ private val src = ByteArrayInputStream(framed)
+ override fun read(): Int = src.read()
+ override fun read(b: ByteArray, off: Int, len: Int): Int =
+ if (len == 0) 0 else { val c = src.read(); if (c < 0) -1 else { b[off] = c.toByte(); 1 } }
+ }
+ assertArrayEquals(payload, DatagramFraming.readFrame(drip))
+ }
+
+ @Test fun readFrame_handles_zero_length_datagram() {
+ val framed = DatagramFraming.encode(ByteArray(0), 0)
+ assertArrayEquals(ByteArray(0), DatagramFraming.readFrame(ByteArrayInputStream(framed)))
+ }
+
+ @Test fun readFrame_handles_max_size_datagram() {
+ val payload = ByteArray(DatagramFraming.MAX_PAYLOAD) { 0x5a }
+ val framed = DatagramFraming.encode(payload, payload.size)
+ assertArrayEquals(payload, DatagramFraming.readFrame(ByteArrayInputStream(framed)))
+ }
+
+ @Test fun readFrame_returns_null_on_clean_eof() {
+ assertNull(DatagramFraming.readFrame(ByteArrayInputStream(ByteArray(0))))
+ }
+
+ @Test(expected = IOException::class)
+ fun readFrame_throws_on_truncated_payload() {
+ // Claims 4 bytes but supplies only 2.
+ val truncated = byteArrayOf(0, 4, 1, 2)
+ DatagramFraming.readFrame(ByteArrayInputStream(truncated))
+ }
+
+ @Test(expected = IllegalArgumentException::class)
+ fun encode_rejects_length_exceeding_payload() {
+ DatagramFraming.encode(byteArrayOf(1, 2), 5)
+ }
+}