Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(csharp): expose download response metadata
wenmou928cbf0791c9
diff --git a/docs/sdks/csharp.md b/docs/sdks/csharp.mdindex 322a8c152..cf926e523 100644--- a/docs/sdks/csharp.md+++ b/docs/sdks/csharp.md@@ -369,6 +369,8 @@ await sandbox.Files.DeleteDirectoriesAsync(new[] { "/tmp/demo" });For binary data, use `byte[]` or `Stream` in `WriteEntry.Data`, and download with `ReadBytesAsync()` or `ReadBytesStreamAsync()`. Read options support partial downloads.+Use `ReadBytesDetailedAsync` or `ReadBytesStreamDetailedAsync` when Range response metadata is required. Dispose a detailed stream body if it is not fully consumed.+#### File operations with an explicit identityBind a filesystem client to a Linux UID and GID:diff --git a/sdks/sandbox/csharp/src/OpenSandbox/Adapters/FilesystemAdapter.cs b/sdks/sandbox/csharp/src/OpenSandbox/Adapters/FilesystemAdapter.csindex 4abb0b0fd..775c2f871 100644--- a/sdks/sandbox/csharp/src/OpenSandbox/Adapters/FilesystemAdapter.cs+++ b/sdks/sandbox/csharp/src/OpenSandbox/Adapters/FilesystemAdapter.cs@@ -16,6 +16,7 @@ using System.Net.Http.Headers;using System.Runtime.CompilerServices;using System.Text;using System.Text.Json;+using System.Text.RegularExpressions;using OpenSandbox.Core;using OpenSandbox.Internal;using OpenSandbox.Models;@@ -33,6 +34,9 @@ internal sealed class FilesystemAdapter : IIdentitySandboxFilesprivate readonly string _baseUrl;private readonly string _identityBaseUrl;private readonly IReadOnlyDictionary<string, string> _headers;+ private static readonly Regex ContentRangeRegex = new(+ @"^bytes\s+(\d+)-(\d+)/(\d+|\*)$",+ RegexOptions.Compiled | RegexOptions.IgnoreCase);private static readonly JsonSerializerOptions JsonOptions = new(){@@ -203,34 +207,69 @@ internal sealed class FilesystemAdapter : IIdentitySandboxFilesReadBytesOptions? options = null,CancellationToken cancellationToken = default){- var headers = new Dictionary<string, string>();- var range = options?.Range;- if (range != null && range.Length > 0)- {- headers["Range"] = range;- }+ var response = await ReadBytesDetailedAsync(path, options, cancellationToken).ConfigureAwait(false);+ return response.Body;+ }- var queryParams = new Dictionary<string, string?>- {- ["path"] = path- };+ public async Task<ReadBytesResponse<byte[]>> ReadBytesDetailedAsync(+ string path,+ ReadBytesOptions? options = null,+ CancellationToken cancellationToken = default)+ {+ using var response = await _client.SendWithWakeRetryAsync(+ () => BuildDownloadRequest(path, options), cancellationToken, _client.SendTransferAsync).ConfigureAwait(false);+ await _client.EnsureSuccessAsync(response, cancellationToken).ConfigureAwait(false);+ var body = await response.Content.ReadAsByteArrayAsync().ConfigureAwait(false);+ return CreateReadBytesResponse(response, body);+ }- if (options?.Offset != null)+ public async IAsyncEnumerable<byte[]> ReadBytesStreamAsync(+ string path,+ ReadBytesOptions? options = null,+ [EnumeratorCancellation] CancellationToken cancellationToken = default)+ {+ var response = await ReadBytesStreamDetailedAsync(path, options, cancellationToken).ConfigureAwait(false);+ await using var body = response.Body;+ await foreach (var chunk in body.WithCancellation(cancellationToken).ConfigureAwait(false)){- queryParams["offset"] = options.Offset.Value.ToString();+ yield return chunk;}- if (options?.Limit != null)+ }++ public async Task<ReadBytesResponse<IAsyncReadBytesStream>> ReadBytesStreamDetailedAsync(+ string path,+ ReadBytesOptions? options = null,+ CancellationToken cancellationToken = default)+ {+ using var request = BuildDownloadRequest(path, options);+ var response = await _client.SendTransferAsync(request, cancellationToken).ConfigureAwait(false);++ if (!response.IsSuccessStatusCode){- queryParams["limit"] = options.Limit.Value.ToString();+ try+ {+ var content = await HttpClientWrapper.ReadContentStringAsync(response.Content, cancellationToken).ConfigureAwait(false);+ var requestId = response.Headers.TryGetValues(Constants.RequestIdHeader, out var values)+ ? values.FirstOrDefault()+ : null;++ throw new SandboxApiException(+ message: "Download stream failed",+ statusCode: (int)response.StatusCode,+ requestId: requestId,+ rawBody: content);+ }+ finally+ {+ response.Dispose();+ }}- return await _client.GetBytesAsync("/files/download", queryParams, headers, cancellationToken).ConfigureAwait(false);+ IAsyncReadBytesStream body = new ResponseByteStream(response, cancellationToken);+ return CreateReadBytesResponse(response, body);}- public async IAsyncEnumerable<byte[]> ReadBytesStreamAsync(- string path,- ReadBytesOptions? options = null,- [EnumeratorCancellation] CancellationToken cancellationToken = default)+ private HttpRequestMessage BuildDownloadRequest(string path, ReadBytesOptions? options){var url = $"{_baseUrl}/files/download?path={Uri.EscapeDataString(path)}";if (options?.Offset != null)@@ -242,43 +281,125 @@ internal sealed class FilesystemAdapter : IIdentitySandboxFilesurl += $"&limit={options.Limit.Value}";}- using var request = new HttpRequestMessage(HttpMethod.Get, url);- foreach (var header in _headers)+ var request = new HttpRequestMessage(HttpMethod.Get, url);+ var range = options?.Range;+ if (!string.IsNullOrEmpty(range)){- request.Headers.TryAddWithoutValidation(header.Key, header.Value);+ request.Headers.TryAddWithoutValidation("Range", range);}+ return request;+ }- var range = options?.Range;- if (range != null && range.Length > 0)+ private static ReadBytesResponse<T> CreateReadBytesResponse<T>(HttpResponseMessage response, T body)+ {+ var isPartial = (int)response.StatusCode == 206;+ var contentLength = response.Content.Headers.ContentLength ?? -1;+ var contentRange = isPartial ? ParseContentRange(GetContentHeader(response, "Content-Range")) : null;+ return new ReadBytesResponse<T>(+ Body: body,+ StatusCode: (int)response.StatusCode,+ ContentType: response.Content.Headers.ContentType?.ToString(),+ ContentDisposition: response.Content.Headers.ContentDisposition?.ToString(),+ ContentLength: contentLength,+ TotalSize: isPartial ? contentRange?.Total ?? -1 : contentLength,+ ContentRange: contentRange);+ }++ private static ByteRange? ParseContentRange(string? raw)+ {+ if (string.IsNullOrEmpty(raw)){- request.Headers.TryAddWithoutValidation("Range", range);+ return null;}- using var response = await _client.SendTransferAsync(request, cancellationToken).ConfigureAwait(false);+ var invalid = new ByteRange(-1, -1, -1, raw!);+ var match = ContentRangeRegex.Match(raw!);+ if (!match.Success ||+ !long.TryParse(match.Groups[1].Value, out var start) ||+ !long.TryParse(match.Groups[2].Value, out var end))+ {+ return invalid;+ }- if (!response.IsSuccessStatusCode)+ var total = -1L;+ if (match.Groups[3].Value != "*" && !long.TryParse(match.Groups[3].Value, out total)){- var content = await HttpClientWrapper.ReadContentStringAsync(response.Content, cancellationToken).ConfigureAwait(false);- var requestId = response.Headers.TryGetValues(Constants.RequestIdHeader, out var values)- ? values.FirstOrDefault()- : null;+ return invalid;+ }+ if (end < start || (total != -1 && total <= end))+ {+ return invalid;+ }+ return new ByteRange(start, end, total, raw!);+ }- throw new SandboxApiException(- message: "Download stream failed",- statusCode: (int)response.StatusCode,- requestId: requestId,- rawBody: content);+ private static string? GetContentHeader(HttpResponseMessage response, string name)+ {+ return response.Content.Headers.TryGetValues(name, out var values)+ ? values.FirstOrDefault()+ : null;+ }++ private sealed class ResponseByteStream : IAsyncReadBytesStream+ {+ private readonly HttpResponseMessage _response;+ private readonly CancellationToken _requestCancellationToken;+ private int _enumerated;+ private int _disposed;++ public ResponseByteStream(+ HttpResponseMessage response,+ CancellationToken requestCancellationToken)+ {+ _response = response;+ _requestCancellationToken = requestCancellationToken;}- var stream = await response.Content.ReadAsStreamAsync().ConfigureAwait(false);- var buffer = new byte[8192];- int bytesRead;+ public IAsyncEnumerator<byte[]> GetAsyncEnumerator(CancellationToken cancellationToken = default)+ {+ if (Interlocked.Exchange(ref _enumerated, 1) != 0)+ {+ throw new InvalidOperationException("Download body can only be read once");+ }+ return ReadChunksAsync(cancellationToken).GetAsyncEnumerator();+ }- while ((bytesRead = await stream.ReadAsync(buffer, 0, buffer.Length, cancellationToken).ConfigureAwait(false)) > 0)+ public ValueTask DisposeAsync(){- var chunk = new byte[bytesRead];- Array.Copy(buffer, chunk, bytesRead);- yield return chunk;+ if (Interlocked.Exchange(ref _disposed, 1) == 0)+ {+ _response.Dispose();+ }+ return default;+ }++ private async IAsyncEnumerable<byte[]> ReadChunksAsync(+ [EnumeratorCancellation] CancellationToken cancellationToken)+ {+ using var linkedCancellation = CancellationTokenSource.CreateLinkedTokenSource(+ _requestCancellationToken,+ cancellationToken);+ try+ {+ using var stream = await _response.Content.ReadAsStreamAsync().ConfigureAwait(false);+ var buffer = new byte[8192];+ int bytesRead;++ while ((bytesRead = await stream.ReadAsync(+ buffer,+ 0,+ buffer.Length,+ linkedCancellation.Token).ConfigureAwait(false)) > 0)+ {+ var chunk = new byte[bytesRead];+ Array.Copy(buffer, chunk, bytesRead);+ yield return chunk;+ }+ }+ finally+ {+ await DisposeAsync().ConfigureAwait(false);+ }}}diff --git a/sdks/sandbox/csharp/src/OpenSandbox/Internal/HttpClientWrapper.cs b/sdks/sandbox/csharp/src/OpenSandbox/Internal/HttpClientWrapper.csindex db8143b57..565f18a62 100644--- a/sdks/sandbox/csharp/src/OpenSandbox/Internal/HttpClientWrapper.cs+++ b/sdks/sandbox/csharp/src/OpenSandbox/Internal/HttpClientWrapper.cs@@ -599,7 +599,7 @@ internal sealed class HttpClientWrapper/// connection request timeout./// </para>/// </summary>- private async Task<HttpResponseMessage> SendWithWakeRetryAsync(+ internal async Task<HttpResponseMessage> SendWithWakeRetryAsync(Func<HttpRequestMessage> requestFactory,CancellationToken cancellationToken,Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>>? sender = null)@@ -724,7 +724,7 @@ internal sealed class HttpClientWrapper}}- private async Task EnsureSuccessAsync(HttpResponseMessage response, CancellationToken cancellationToken)+ internal async Task EnsureSuccessAsync(HttpResponseMessage response, CancellationToken cancellationToken){if (!response.IsSuccessStatusCode){diff --git a/sdks/sandbox/csharp/src/OpenSandbox/Models/Filesystem.cs b/sdks/sandbox/csharp/src/OpenSandbox/Models/Filesystem.csindex c140c5c7d..caafc9911 100644--- a/sdks/sandbox/csharp/src/OpenSandbox/Models/Filesystem.cs+++ b/sdks/sandbox/csharp/src/OpenSandbox/Models/Filesystem.cs@@ -16,6 +16,36 @@ using System.Text.Json.Serialization;namespace OpenSandbox.Models;+/// <summary>+/// Parsed Content-Range response header.+/// </summary>+public sealed record ByteRange(long Start, long End, long Total, string Raw);++/// <summary>+/// Downloaded body and its HTTP response metadata.+/// </summary>+public sealed record ReadBytesResponse<T>(+ T Body,+ int StatusCode,+ string? ContentType,+ string? ContentDisposition,+ long ContentLength,+ long TotalSize,+ ByteRange? ContentRange)+{+ /// <summary>+ /// Gets whether the server returned 206 Partial Content.+ /// </summary>+ public bool IsPartial => StatusCode == 206;+}++/// <summary>+/// A single-use download body that can be disposed without consuming it.+/// </summary>+public interface IAsyncReadBytesStream : IAsyncEnumerable<byte[]>, IAsyncDisposable+{+}+/// <summary>/// Information about a file in the sandbox./// </summary>diff --git a/sdks/sandbox/csharp/src/OpenSandbox/Services/ISandboxFiles.cs b/sdks/sandbox/csharp/src/OpenSandbox/Services/ISandboxFiles.csindex 71842fb85..d3bc6dfe1 100644--- a/sdks/sandbox/csharp/src/OpenSandbox/Services/ISandboxFiles.cs+++ b/sdks/sandbox/csharp/src/OpenSandbox/Services/ISandboxFiles.cs@@ -121,6 +121,20 @@ public interface ISandboxFilesReadBytesOptions? options = null,CancellationToken cancellationToken = default);+ /// <summary>+ /// Reads a file as bytes together with HTTP response metadata.+ /// </summary>+ /// <param name="path">The file path.</param>+ /// <param name="options">Optional read options.</param>+ /// <param name="cancellationToken">Cancellation token.</param>+ /// <returns>The file content and HTTP response metadata.</returns>+ /// <exception cref="InvalidArgumentException">Thrown when request values are invalid.</exception>+ /// <exception cref="SandboxException">Thrown when the execd service request fails.</exception>+ Task<ReadBytesResponse<byte[]>> ReadBytesDetailedAsync(+ string path,+ ReadBytesOptions? options = null,+ CancellationToken cancellationToken = default);+/// <summary>/// Reads a file as a stream of byte chunks./// </summary>@@ -135,6 +149,20 @@ public interface ISandboxFilesReadBytesOptions? options = null,CancellationToken cancellationToken = default);+ /// <summary>+ /// Reads a file as a byte stream together with HTTP response metadata.+ /// </summary>+ /// <param name="path">The file path.</param>+ /// <param name="options">Optional read options.</param>+ /// <param name="cancellationToken">Cancellation token.</param>+ /// <returns>The byte stream and HTTP response metadata.</returns>+ /// <exception cref="InvalidArgumentException">Thrown when request values are invalid.</exception>+ /// <exception cref="SandboxException">Thrown when the execd service request fails.</exception>+ Task<ReadBytesResponse<IAsyncReadBytesStream>> ReadBytesStreamDetailedAsync(+ string path,+ ReadBytesOptions? options = null,+ CancellationToken cancellationToken = default);+/// <summary>/// Deletes files at the specified paths./// </summary>diff --git a/sdks/sandbox/csharp/tests/OpenSandbox.Tests/FilesystemAdapterTests.cs b/sdks/sandbox/csharp/tests/OpenSandbox.Tests/FilesystemAdapterTests.csindex feceba9c7..ac74222a5 100644--- a/sdks/sandbox/csharp/tests/OpenSandbox.Tests/FilesystemAdapterTests.cs+++ b/sdks/sandbox/csharp/tests/OpenSandbox.Tests/FilesystemAdapterTests.cs@@ -17,6 +17,7 @@ using System.Text;using FluentAssertions;using OpenSandbox.Adapters;using OpenSandbox.Internal;+using OpenSandbox.Models;using Xunit;namespace OpenSandbox.Tests;@@ -157,6 +158,149 @@ public class FilesystemAdapterTestsentries.Should().BeEmpty();}+ [Fact]+ public async Task ReadBytesDetailedAsync_ShouldExposePartialMetadata()+ {+ var handler = new DownloadHandler();+ handler.Enqueue(DownloadResponse(+ HttpStatusCode.PartialContent,+ "hello",+ contentRange: "bytes 0-4/10",+ contentType: "application/octet-stream",+ contentDisposition: "attachment; filename=\"data.bin\""));+ using var client = new HttpClient(handler);+ var adapter = CreateAdapter(client);++ var response = await adapter.ReadBytesDetailedAsync(+ "/data.bin",+ new ReadBytesOptions { Range = "bytes=0-4" });++ response.Body.Should().Equal(Encoding.UTF8.GetBytes("hello"));+ response.StatusCode.Should().Be(206);+ response.IsPartial.Should().BeTrue();+ response.ContentType.Should().Be("application/octet-stream");+ response.ContentDisposition.Should().Be("attachment; filename=\"data.bin\"");+ response.ContentLength.Should().Be(5);+ response.TotalSize.Should().Be(10);+ response.ContentRange.Should().Be(new ByteRange(0, 4, 10, "bytes 0-4/10"));+ handler.LastRange.Should().Be("bytes=0-4");+ }++ [Fact]+ public async Task ReadBytesDetailedAsync_ShouldIdentifyIgnoredRange()+ {+ var handler = new DownloadHandler();+ handler.Enqueue(DownloadResponse(HttpStatusCode.OK, "whole file"));+ using var client = new HttpClient(handler);+ var adapter = CreateAdapter(client);++ var response = await adapter.ReadBytesDetailedAsync(+ "/data.bin",+ new ReadBytesOptions { Range = "bytes=5-" });++ response.IsPartial.Should().BeFalse();+ response.ContentRange.Should().BeNull();+ response.ContentLength.Should().Be(10);+ response.TotalSize.Should().Be(10);+ }++ [Fact]+ public async Task ReadBytesDetailedAsync_ShouldPreserveInvalidAndUnknownRanges()+ {+ var handler = new DownloadHandler();+ handler.Enqueue(DownloadResponse(HttpStatusCode.PartialContent, "hello", "garbage"));+ handler.Enqueue(DownloadResponse(HttpStatusCode.PartialContent, "hello", "bytes 5-9/*"));+ using var client = new HttpClient(handler);+ var adapter = CreateAdapter(client);++ var invalid = await adapter.ReadBytesDetailedAsync("/data.bin");+ var unknown = await adapter.ReadBytesDetailedAsync("/data.bin");++ invalid.ContentRange.Should().Be(new ByteRange(-1, -1, -1, "garbage"));+ invalid.TotalSize.Should().Be(-1);+ unknown.ContentRange.Should().Be(new ByteRange(5, 9, -1, "bytes 5-9/*"));+ unknown.TotalSize.Should().Be(-1);+ }++ [Fact]+ public async Task DetailedAndLegacyReads_ShouldReturnResponseBodies()+ {+ var handler = new DownloadHandler();+ handler.Enqueue(DownloadResponse(HttpStatusCode.PartialContent, "hello", "bytes 0-4/10"));+ handler.Enqueue(DownloadResponse(HttpStatusCode.OK, "hello"));+ handler.Enqueue(DownloadResponse(HttpStatusCode.OK, "hello"));+ using var client = new HttpClient(handler);+ var adapter = CreateAdapter(client);++ var detailed = await adapter.ReadBytesStreamDetailedAsync("/data.bin");+ detailed.IsPartial.Should().BeTrue();+ (await CollectAsync(detailed.Body)).Should().Equal(Encoding.UTF8.GetBytes("hello"));+ (await adapter.ReadBytesAsync("/data.bin")).Should().Equal(Encoding.UTF8.GetBytes("hello"));+ (await CollectAsync(adapter.ReadBytesStreamAsync("/data.bin"))).Should().Equal(Encoding.UTF8.GetBytes("hello"));+ }++ [Fact]+ public async Task DetailedStreams_ShouldDisposeUnconsumedAndPartialBodies()+ {+ var unconsumedContent = new TrackingContent("hello");+ var partialContent = new TrackingContent("hello");+ var handler = new DownloadHandler();+ handler.Enqueue(new HttpResponseMessage(HttpStatusCode.PartialContent) { Content = unconsumedContent });+ handler.Enqueue(new HttpResponseMessage(HttpStatusCode.PartialContent) { Content = partialContent });+ using var client = new HttpClient(handler);+ var adapter = CreateAdapter(client);++ var unconsumed = await adapter.ReadBytesStreamDetailedAsync("/data.bin");+ await unconsumed.Body.DisposeAsync();+ unconsumedContent.Disposed.Should().BeTrue();++ var partial = await adapter.ReadBytesStreamDetailedAsync("/data.bin");+ await foreach (var _ in partial.Body)+ {+ break;+ }+ partialContent.Disposed.Should().BeTrue();+ }++ private static FilesystemAdapter CreateAdapter(HttpClient client)+ {+ var wrapper = new HttpClientWrapper(client, "http://localhost:8080");+ return new FilesystemAdapter(wrapper, client, "http://localhost:8080", new Dictionary<string, string>());+ }++ private static HttpResponseMessage DownloadResponse(+ HttpStatusCode statusCode,+ string body,+ string? contentRange = null,+ string? contentType = null,+ string? contentDisposition = null)+ {+ var content = new ByteArrayContent(Encoding.UTF8.GetBytes(body));+ if (contentRange != null)+ {+ content.Headers.TryAddWithoutValidation("Content-Range", contentRange);+ }+ if (contentType != null)+ {+ content.Headers.TryAddWithoutValidation("Content-Type", contentType);+ }+ if (contentDisposition != null)+ {+ content.Headers.TryAddWithoutValidation("Content-Disposition", contentDisposition);+ }+ return new HttpResponseMessage(statusCode) { Content = content };+ }++ private static async Task<byte[]> CollectAsync(IAsyncEnumerable<byte[]> chunks)+ {+ using var stream = new MemoryStream();+ await foreach (var chunk in chunks)+ {+ await stream.WriteAsync(chunk);+ }+ return stream.ToArray();+ }+private sealed class CaptureJsonHandler(string payload) : HttpMessageHandler{public Uri? LastRequestUri { get; private set; }@@ -171,4 +315,34 @@ public class FilesystemAdapterTestsreturn Task.FromResult(response);}}++ private sealed class DownloadHandler : HttpMessageHandler+ {+ private readonly Queue<HttpResponseMessage> _responses = new();++ public string? LastRange { get; private set; }++ public void Enqueue(HttpResponseMessage response) => _responses.Enqueue(response);++ protected override Task<HttpResponseMessage> SendAsync(+ HttpRequestMessage request,+ CancellationToken cancellationToken)+ {+ LastRange = request.Headers.TryGetValues("Range", out var values)+ ? values.SingleOrDefault()+ : null;+ return Task.FromResult(_responses.Dequeue());+ }+ }++ private sealed class TrackingContent(string body) : ByteArrayContent(Encoding.UTF8.GetBytes(body))+ {+ public bool Disposed { get; private set; }++ protected override void Dispose(bool disposing)+ {+ Disposed = true;+ base.Dispose(disposing);+ }+ }}diff --git a/sdks/sandbox/csharp/tests/OpenSandbox.Tests/SandboxEgressLifecycleTests.cs b/sdks/sandbox/csharp/tests/OpenSandbox.Tests/SandboxEgressLifecycleTests.csindex dc146f7bc..5132244b6 100644--- a/sdks/sandbox/csharp/tests/OpenSandbox.Tests/SandboxEgressLifecycleTests.cs+++ b/sdks/sandbox/csharp/tests/OpenSandbox.Tests/SandboxEgressLifecycleTests.cs@@ -929,9 +929,15 @@ public class SandboxEgressLifecycleTestspublic Task<byte[]> ReadBytesAsync(string path, ReadBytesOptions? options = null, CancellationToken cancellationToken = default) =>throw new NotImplementedException();+ public Task<ReadBytesResponse<byte[]>> ReadBytesDetailedAsync(string path, ReadBytesOptions? options = null, CancellationToken cancellationToken = default) =>+ throw new NotImplementedException();+public IAsyncEnumerable<byte[]> ReadBytesStreamAsync(string path, ReadBytesOptions? options = null, CancellationToken cancellationToken = default) =>AsyncEnumerable.Empty<byte[]>();+ public Task<ReadBytesResponse<IAsyncReadBytesStream>> ReadBytesStreamDetailedAsync(string path, ReadBytesOptions? options = null, CancellationToken cancellationToken = default) =>+ throw new NotImplementedException();+public Task DeleteFilesAsync(IEnumerable<string> paths, CancellationToken cancellationToken = default) =>throw new NotImplementedException();