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.mdindex 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 identityBind 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.ktindex 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.filesystemimport 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.ktindex 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.ContentRepimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ContentReplaceResultimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.EntryInfoimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.MoveEntry+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ReadBytesResponseimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SearchEntryimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SetPermissionEntryimport 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.ktnew file mode 100644index 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.ktindex 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.ContentRepimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ContentReplaceResultimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.EntryInfoimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.MoveEntry+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ReadBytesResponseimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SearchEntryimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SetPermissionEntryimport 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.ktindex 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.ContentRepimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ContentReplaceResultimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.EntryInfoimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.MoveEntry+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ReadBytesResponseimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SearchEntryimport com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.SetPermissionEntryimport 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.ktindex 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.HttpClientProviderimport com.alibaba.opensandbox.sandbox.config.ConnectionConfigimport com.alibaba.opensandbox.sandbox.domain.exceptions.SandboxApiExceptionimport com.alibaba.opensandbox.sandbox.domain.exceptions.SandboxError+import com.alibaba.opensandbox.sandbox.domain.models.execd.filesystem.ByteRangeimport com.alibaba.opensandbox.sandbox.domain.models.sandboxes.SandboxEndpointimport com.alibaba.opensandbox.sandbox.domain.services.IdentityFilesystemimport com.alibaba.opensandbox.sandbox.infrastructure.adapters.converter.isFileNotFoundimport okhttp3.mockwebserver.MockResponseimport okhttp3.mockwebserver.MockWebServerimport org.junit.jupiter.api.AfterEach+import org.junit.jupiter.api.Assertions.assertArrayEqualsimport org.junit.jupiter.api.Assertions.assertEqualsimport org.junit.jupiter.api.Assertions.assertFalse+import org.junit.jupiter.api.Assertions.assertNullimport org.junit.jupiter.api.Assertions.assertTrueimport org.junit.jupiter.api.BeforeEachimport 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())+ }+ }+@Testfun `isFileNotFound is true for FILE_NOT_FOUND error code`() {val exception =