Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

fix(kotlin): expose download response metadata

wenmoufcdca055c915
diff --git a/docs/sdks/kotlin.md b/docs/sdks/kotlin.md
index d418c7e8c..5c16c4f45 100644
--- a/docs/sdks/kotlin.md
+++ b/docs/sdks/kotlin.md
@@ -391,6 +391,8 @@ files.forEach(f -> System.out.println("Found: " + f.getPath()));
sandbox.files().deleteFiles(List.of("/tmp/hello.txt"));
```
+Use `readByteArrayDetailed` or `readStreamDetailed` when Range response metadata is required.
+
#### File operations with an explicit identity
Bind a filesystem client to a Linux UID and GID:
diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/execd/filesystem/FilesystemModels.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/execd/filesystem/FilesystemModels.kt
index 2843ec942..2094357ff 100644
--- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/execd/filesystem/FilesystemModels.kt
+++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/execd/filesystem/FilesystemModels.kt
@@ -18,6 +18,29 @@ package com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem
import java.time.OffsetDateTime
+/** Parsed Content-Range response header. */
+data class ByteRange(
+ val start: Long,
+ val end: Long,
+ val total: Long,
+ val raw: String,
+)
+
+/** Downloaded body and its HTTP response metadata. */
+data class ReadBytesResponse<T>(
+ val body: T,
+ val statusCode: Int,
+ val contentType: String?,
+ val contentDisposition: String?,
+ val contentLength: Long,
+ val totalSize: Long,
+ val contentRange: ByteRange?,
+) {
+ /** Whether the server returned 206 Partial Content. */
+ val isPartial: Boolean
+ get() = statusCode == 206
+}
+
/**
* Metadata information for a file or directory entry.
*
diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/services/Filesystem.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/services/Filesystem.kt
index 988334a4d..93a154e26 100644
--- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/services/Filesystem.kt
+++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/services/Filesystem.kt
@@ -20,6 +20,7 @@ import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ContentRep
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ContentReplaceResult
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.EntryInfo
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.MoveEntry
+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ReadBytesResponse
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SearchEntry
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SetPermissionEntry
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.WriteEntry
@@ -115,6 +116,16 @@ interface Filesystem {
return readByteArray(path, null)
}
+ /**
+ * Reads a file as a byte array together with HTTP response metadata.
+ */
+ fun readByteArrayDetailed(
+ path: String,
+ range: String? = null,
+ offset: Int? = null,
+ limit: Int? = null,
+ ): ReadBytesResponse<ByteArray>
+
/**
* Opens a file for reading as an InputStream.
*
@@ -154,6 +165,16 @@ interface Filesystem {
return readStream(path, null)
}
+ /**
+ * Opens a file stream together with HTTP response metadata.
+ */
+ fun readStreamDetailed(
+ path: String,
+ range: String? = null,
+ offset: Int? = null,
+ limit: Int? = null,
+ ): ReadBytesResponse<InputStream>
+
/**
* Writes content to files based on the provided write entries.
*
diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/DownloadResponseMapper.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/DownloadResponseMapper.kt
new file mode 100644
index 000000000..341e13f5e
--- /dev/null
+++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/DownloadResponseMapper.kt
@@ -0,0 +1,55 @@
+/*
+ * Copyright 2026 Alibaba Group Holding Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.alibaba.opensandbox.sandbox.infrastructure.adapters.service
+
+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ByteRange
+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ReadBytesResponse
+import okhttp3.Response
+
+private val contentRangeRegex = Regex("""^bytes\s+(\d+)-(\d+)/(\d+|\*)$""", RegexOption.IGNORE_CASE)
+
+private fun parseContentRange(raw: String?): ByteRange? {
+ if (raw.isNullOrEmpty()) return null
+
+ val invalid = ByteRange(start = -1, end = -1, total = -1, raw = raw)
+ val match = contentRangeRegex.matchEntire(raw) ?: return invalid
+ val start = match.groupValues[1].toLongOrNull() ?: return invalid
+ val end = match.groupValues[2].toLongOrNull() ?: return invalid
+ val total =
+ if (match.groupValues[3] == "*") {
+ -1
+ } else {
+ match.groupValues[3].toLongOrNull() ?: return invalid
+ }
+ if (end < start || (total != -1L && total <= end)) return invalid
+ return ByteRange(start = start, end = end, total = total, raw = raw)
+}
+
+internal fun <T> Response.toReadBytesResponse(body: T): ReadBytesResponse<T> {
+ val isPartial = code == 206
+ val contentLength = header("Content-Length")?.toLongOrNull()?.takeIf { it >= 0 } ?: -1
+ val contentRange = if (isPartial) parseContentRange(header("Content-Range")) else null
+ return ReadBytesResponse(
+ body = body,
+ statusCode = code,
+ contentType = header("Content-Type"),
+ contentDisposition = header("Content-Disposition"),
+ contentLength = contentLength,
+ totalSize = if (isPartial) contentRange?.total ?: -1 else contentLength,
+ contentRange = contentRange,
+ )
+}
diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapter.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapter.kt
index 414b7e457..0d2f97880 100644
--- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapter.kt
+++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapter.kt
@@ -23,6 +23,7 @@ import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ContentRep
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ContentReplaceResult
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.EntryInfo
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.MoveEntry
+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ReadBytesResponse
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SearchEntry
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SetPermissionEntry
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.WriteEntry
@@ -139,7 +140,14 @@ internal class FilesystemAdapter(
range: String?,
offset: Int?,
limit: Int?,
- ): ByteArray {
+ ): ByteArray = readByteArrayDetailed(path, range, offset, limit).body
+
+ override fun readByteArrayDetailed(
+ path: String,
+ range: String?,
+ offset: Int?,
+ limit: Int?,
+ ): ReadBytesResponse<ByteArray> {
try {
val request = buildDownloadRequest(path, range, offset, limit)
httpClientProvider.transferClient.newCall(request).execute().use { response ->
@@ -148,7 +156,8 @@ internal class FilesystemAdapter(
"Failed to read file. Status code: $statusCode, Body: $body"
}
}
- return response.body?.bytes() ?: ByteArray(0)
+ val body = response.body?.bytes() ?: ByteArray(0)
+ return response.toReadBytesResponse(body)
}
} catch (e: Exception) {
logReadFailure("Failed to read file as byte array: $path", e)
@@ -161,7 +170,14 @@ internal class FilesystemAdapter(
range: String?,
offset: Int?,
limit: Int?,
- ): InputStream {
+ ): InputStream = readStreamDetailed(path, range, offset, limit).body
+
+ override fun readStreamDetailed(
+ path: String,
+ range: String?,
+ offset: Int?,
+ limit: Int?,
+ ): ReadBytesResponse<InputStream> {
try {
val request = buildDownloadRequest(path, range, offset, limit)
val response = httpClientProvider.transferClient.newCall(request).execute()
@@ -177,8 +193,12 @@ internal class FilesystemAdapter(
}
}
- return response.body?.byteStream()
- ?: throw IllegalStateException("Response body is null")
+ val responseBody =
+ response.body ?: run {
+ response.close()
+ throw IllegalStateException("Response body is null")
+ }
+ return response.toReadBytesResponse(responseBody.byteStream())
} catch (e: Exception) {
logReadFailure("Failed to read file as stream: $path", e)
throw e.toSandboxException()
diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/IsolatedFilesystemAdapter.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/IsolatedFilesystemAdapter.kt
index 1b1d47bae..4032bb7ef 100644
--- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/IsolatedFilesystemAdapter.kt
+++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/IsolatedFilesystemAdapter.kt
@@ -23,6 +23,7 @@ import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ContentRep
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ContentReplaceResult
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.EntryInfo
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.MoveEntry
+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ReadBytesResponse
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SearchEntry
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SetPermissionEntry
import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.WriteEntry
@@ -118,7 +119,14 @@ internal class IsolatedFilesystemAdapter(
range: String?,
offset: Int?,
limit: Int?,
- ): ByteArray {
+ ): ByteArray = readByteArrayDetailed(path, range, offset, limit).body
+
+ override fun readByteArrayDetailed(
+ path: String,
+ range: String?,
+ offset: Int?,
+ limit: Int?,
+ ): ReadBytesResponse<ByteArray> {
try {
val request = buildDownloadRequest(path, range, offset, limit)
httpClientProvider.transferClient.newCall(request).execute().use { response ->
@@ -127,7 +135,8 @@ internal class IsolatedFilesystemAdapter(
"Failed to read file. Status code: $statusCode, Body: $body"
}
}
- return response.body?.bytes() ?: ByteArray(0)
+ val body = response.body?.bytes() ?: ByteArray(0)
+ return response.toReadBytesResponse(body)
}
} catch (e: Exception) {
logReadFailure("Failed to read file as byte array: $path", e)
@@ -140,7 +149,14 @@ internal class IsolatedFilesystemAdapter(
range: String?,
offset: Int?,
limit: Int?,
- ): InputStream {
+ ): InputStream = readStreamDetailed(path, range, offset, limit).body
+
+ override fun readStreamDetailed(
+ path: String,
+ range: String?,
+ offset: Int?,
+ limit: Int?,
+ ): ReadBytesResponse<InputStream> {
try {
val request = buildDownloadRequest(path, range, offset, limit)
val response = httpClientProvider.transferClient.newCall(request).execute()
@@ -154,8 +170,12 @@ internal class IsolatedFilesystemAdapter(
throw e
}
}
- return response.body?.byteStream()
- ?: throw IllegalStateException("Response body is null")
+ val responseBody =
+ response.body ?: run {
+ response.close()
+ throw IllegalStateException("Response body is null")
+ }
+ return response.toReadBytesResponse(responseBody.byteStream())
} catch (e: Exception) {
logReadFailure("Failed to read file as stream: $path", e)
throw e.toSandboxException()
diff --git a/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapterTest.kt b/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapterTest.kt
index cec7e398d..d43db1be3 100644
--- a/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapterTest.kt
+++ b/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/FilesystemAdapterTest.kt
@@ -20,14 +20,17 @@ import com.alibaba.opensandbox.sandbox.HttpClientProvider
import com.alibaba.opensandbox.sandbox.config.ConnectionConfig
import com.alibaba.opensandbox.sandbox.domain.exceptions.SandboxApiException
import com.alibaba.opensandbox.sandbox.domain.exceptions.SandboxError
+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ByteRange
import com.alibaba.opensandbox.sandbox.domain.models.sandboxes.SandboxEndpoint
import com.alibaba.opensandbox.sandbox.domain.services.IdentityFilesystem
import com.alibaba.opensandbox.sandbox.infrastructure.adapters.converter.isFileNotFound
import okhttp3.mockwebserver.MockResponse
import okhttp3.mockwebserver.MockWebServer
import org.junit.jupiter.api.AfterEach
+import org.junit.jupiter.api.Assertions.assertArrayEquals
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertFalse
+import org.junit.jupiter.api.Assertions.assertNull
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.BeforeEach
import org.junit.jupiter.api.Test
@@ -170,6 +173,85 @@ class FilesystemAdapterTest {
assertEquals("hello world", content)
}
+ @Test
+ fun `readByteArrayDetailed exposes partial response metadata`() {
+ mockWebServer.enqueue(
+ MockResponse()
+ .setResponseCode(206)
+ .setHeader("Content-Type", "application/octet-stream")
+ .setHeader("Content-Disposition", "attachment; filename=\"data.bin\"")
+ .setHeader("Content-Range", "bytes 0-4/10")
+ .setBody("hello"),
+ )
+
+ val response = filesystemAdapter.readByteArrayDetailed("/data.bin", "bytes=0-4")
+
+ assertArrayEquals("hello".toByteArray(), response.body)
+ assertEquals(206, response.statusCode)
+ assertTrue(response.isPartial)
+ assertEquals("application/octet-stream", response.contentType)
+ assertEquals("attachment; filename=\"data.bin\"", response.contentDisposition)
+ assertEquals(5, response.contentLength)
+ assertEquals(10, response.totalSize)
+ assertEquals(ByteRange(0, 4, 10, "bytes 0-4/10"), response.contentRange)
+ assertEquals("bytes=0-4", mockWebServer.takeRequest().getHeader("Range"))
+ }
+
+ @Test
+ fun `readByteArrayDetailed identifies an ignored Range request`() {
+ mockWebServer.enqueue(
+ MockResponse()
+ .setResponseCode(200)
+ .setBody("whole file"),
+ )
+
+ val response = filesystemAdapter.readByteArrayDetailed("/data.bin", "bytes=5-")
+
+ assertFalse(response.isPartial)
+ assertNull(response.contentRange)
+ assertEquals(10, response.contentLength)
+ assertEquals(10, response.totalSize)
+ }
+
+ @Test
+ fun `readByteArrayDetailed preserves invalid and unknown Content-Range values`() {
+ mockWebServer.enqueue(
+ MockResponse()
+ .setResponseCode(206)
+ .setHeader("Content-Range", "garbage")
+ .setBody("hello"),
+ )
+ mockWebServer.enqueue(
+ MockResponse()
+ .setResponseCode(206)
+ .setHeader("Content-Range", "bytes 5-9/*")
+ .setBody("hello"),
+ )
+
+ val invalid = filesystemAdapter.readByteArrayDetailed("/data.bin")
+ val unknown = filesystemAdapter.readByteArrayDetailed("/data.bin")
+
+ assertEquals(ByteRange(-1, -1, -1, "garbage"), invalid.contentRange)
+ assertEquals(-1, invalid.totalSize)
+ assertEquals(ByteRange(5, 9, -1, "bytes 5-9/*"), unknown.contentRange)
+ assertEquals(-1, unknown.totalSize)
+ }
+
+ @Test
+ fun `detailed and legacy reads return response bodies`() {
+ mockWebServer.enqueue(MockResponse().setResponseCode(200).setBody("hello"))
+ mockWebServer.enqueue(MockResponse().setResponseCode(200).setBody("hello"))
+ mockWebServer.enqueue(MockResponse().setResponseCode(200).setBody("hello"))
+
+ filesystemAdapter.readStreamDetailed("/data.bin").body.use { stream ->
+ assertArrayEquals("hello".toByteArray(), stream.readBytes())
+ }
+ assertArrayEquals("hello".toByteArray(), filesystemAdapter.readByteArray("/data.bin"))
+ filesystemAdapter.readStream("/data.bin").use { stream ->
+ assertArrayEquals("hello".toByteArray(), stream.readBytes())
+ }
+ }
+
@Test
fun `isFileNotFound is true for FILE_NOT_FOUND error code`() {
val exception =