boxd 0.2.10.dev615__tar.gz → 0.2.10.dev616__tar.gz

{boxd-0.2.10.dev615/src/boxd.egg-info → boxd-0.2.10.dev616}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.2.10.dev615
+Version: 0.2.10.dev616
 Summary: Python SDK for the boxd cloud VM platform
 Author: Azin
 License-Expression: MIT

{boxd-0.2.10.dev615 → boxd-0.2.10.dev616}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boxd"
-version = "0.2.10.dev615"
+version = "0.2.10.dev616"
 description = "Python SDK for the boxd cloud VM platform"
 readme = "README.md"
 license = "MIT"

{boxd-0.2.10.dev615 → boxd-0.2.10.dev616}/src/boxd/models.py

@@ -172,10 +172,17 @@ class Machine(BaseModel):
 
 
 class ExecResult(BaseModel):
-    """A one-shot `machines.exec`."""
+    """A one-shot `machines.exec`.
 
-    stdout: str
-    stderr: str
+    `stdout`/`stderr` are `str`, UTF-8-decoded, unless `encoding="buffer"`
+    was passed to `exec`, in which case they're the raw `bytes` instead. The
+    default decode is lossy — any invalid byte sequence is replaced with
+    U+FFFD — so binary output (or output you need byte-exact) should use
+    `encoding="buffer"` or `stream_exec`, which is always byte-exact.
+    """
+
+    stdout: str | bytes
+    stderr: str | bytes
     exit_code: int
 
     @property

{boxd-0.2.10.dev615 → boxd-0.2.10.dev616}/src/boxd/resources/machines.py

@@ -158,7 +158,26 @@ def _exec_timeout(timeout: float | None):
         raise
 
 
-def _collect_exec(chunks) -> ExecResult:
+def _finish_exec(
+    stdout: bytes, stderr: bytes, exit_code: int, encoding: str
+) -> ExecResult:
+    """Build the final `ExecResult`, honoring `encoding`.
+
+    `"buffer"` returns the raw bytes untouched — byte-exact, same as
+    `stream_exec`. Anything else (default `"utf-8"`) decodes lossily: any
+    invalid byte sequence is replaced with U+FFFD, so binary output should
+    use `"buffer"` instead (see `ExecResult`).
+    """
+    if encoding == "buffer":
+        return ExecResult(stdout=stdout, stderr=stderr, exit_code=exit_code)
+    return ExecResult(
+        stdout=stdout.decode("utf-8", errors="replace"),
+        stderr=stderr.decode("utf-8", errors="replace"),
+        exit_code=exit_code,
+    )
+
+
+def _collect_exec(chunks, encoding: str = "utf-8") -> ExecResult:
     """Fold an `Exec` response stream into a one-shot result."""
     stdout: list[bytes] = []
     stderr: list[bytes] = []
@@ -167,11 +186,7 @@ def _collect_exec(chunks) -> ExecResult:
         if chunk.data:
             (stderr if chunk.is_stderr else stdout).append(chunk.data)
         exit_code = chunk.exit_code
-    return ExecResult(
-        stdout=b"".join(stdout).decode("utf-8", errors="replace"),
-        stderr=b"".join(stderr).decode("utf-8", errors="replace"),
-        exit_code=exit_code,
-    )
+    return _finish_exec(b"".join(stdout), b"".join(stderr), exit_code, encoding)
 
 
 def _ready_check(machine: Machine, name: str) -> bool:
@@ -485,6 +500,7 @@ class Machines(Namespace):
         cols: int = 0,
         rows: int = 0,
         timeout: float | None = None,
+        encoding: Literal["utf-8", "buffer"] = "utf-8",
     ) -> ExecResult:
         """Run one command and collect its output.
 
@@ -495,6 +511,11 @@ class Machines(Namespace):
         fails fast (the remote `cd` errors and the command never runs)
         instead of silently running in the default directory.
 
+        `stdout`/`stderr` are UTF-8-decoded by default, which silently
+        replaces any invalid byte sequence with U+FFFD — pass
+        `encoding="buffer"` for byte-exact `bytes` output instead (e.g.
+        `head -c 4096 /dev/urandom`).
+
         `timeout` is in seconds and gives up on the call; the server kills
         the remote process's whole process group (SIGTERM, then SIGKILL
         after a short grace period if it hasn't exited) rather than leaving
@@ -505,7 +526,8 @@ class Machines(Namespace):
         )
         with _exec_timeout(timeout):
             return _collect_exec(
-                self._transport.bidi("Exec", iter([init]), timeout=timeout)
+                self._transport.bidi("Exec", iter([init]), timeout=timeout),
+                encoding=encoding,
             )
 
     def stream_exec(
@@ -1119,6 +1141,7 @@ class AsyncMachines(Namespace):
         cols: int = 0,
         rows: int = 0,
         timeout: float | None = None,
+        encoding: Literal["utf-8", "buffer"] = "utf-8",
     ) -> ExecResult:
         """Run one command and collect its output.
 
@@ -1129,6 +1152,11 @@ class AsyncMachines(Namespace):
         fails fast (the remote `cd` errors and the command never runs)
         instead of silently running in the default directory.
 
+        `stdout`/`stderr` are UTF-8-decoded by default, which silently
+        replaces any invalid byte sequence with U+FFFD — pass
+        `encoding="buffer"` for byte-exact `bytes` output instead (e.g.
+        `head -c 4096 /dev/urandom`).
+
         `timeout` is in seconds and gives up on the call; the server kills
         the remote process's whole process group (SIGTERM, then SIGKILL
         after a short grace period if it hasn't exited) rather than leaving
@@ -1150,11 +1178,7 @@ class AsyncMachines(Namespace):
                 if chunk.data:
                     (stderr if chunk.is_stderr else stdout).append(chunk.data)
                 exit_code = chunk.exit_code
-        return ExecResult(
-            stdout=b"".join(stdout).decode("utf-8", errors="replace"),
-            stderr=b"".join(stderr).decode("utf-8", errors="replace"),
-            exit_code=exit_code,
-        )
+        return _finish_exec(b"".join(stdout), b"".join(stderr), exit_code, encoding)
 
     def stream_exec(
         self,

{boxd-0.2.10.dev615 → boxd-0.2.10.dev616/src/boxd.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.2.10.dev615
+Version: 0.2.10.dev616
 Summary: Python SDK for the boxd cloud VM platform
 Author: Azin
 License-Expression: MIT

{boxd-0.2.10.dev615 → boxd-0.2.10.dev616}/tests/test_namespaces.py

@@ -186,6 +186,24 @@ def test_exec_folds_the_stream_into_one_result():
     assert transport.sent[0].vm_id == "alpha"
 
 
+def test_exec_default_encoding_corrupts_invalid_utf8():
+    # BOX-280: the default string mode is lossy — invalid bytes become
+    # U+FFFD and the byte length changes. Documents the failure this issue
+    # is about, alongside the encoding="buffer" escape hatch below.
+    transport = FakeTransport([[api_pb2.ExecChunk(data=b"\x00\x01\xff\xfe", exit_code=0)]])
+    result = Machines(transport).exec("alpha", "printf '\\000\\001\\377\\376'")
+    assert result.stdout == "\x00\x01��"
+    assert isinstance(result.stdout, str)
+
+
+def test_exec_buffer_encoding_is_byte_exact():
+    raw = bytes(range(256))
+    transport = FakeTransport([[api_pb2.ExecChunk(data=raw, exit_code=0)]])
+    result = Machines(transport).exec("alpha", "cat", encoding="buffer")
+    assert result.stdout == raw
+    assert isinstance(result.stdout, bytes)
+
+
 def test_exec_prefixes_env_assignments():
     transport = FakeTransport([[api_pb2.ExecChunk(exit_code=0)]])
     Machines(transport).exec("alpha", "env", env={"MODE": "a b"})
@@ -672,6 +690,14 @@ async def test_async_exec_folds_the_stream():
     assert result.exit_code == 0
 
 
+async def test_async_exec_buffer_encoding_is_byte_exact():
+    raw = bytes(range(256))
+    transport = FakeAsyncTransport([[api_pb2.ExecChunk(data=raw, exit_code=0)]])
+    result = await AsyncMachines(transport).exec("alpha", "cat", encoding="buffer")
+    assert result.stdout == raw
+    assert isinstance(result.stdout, bytes)
+
+
 async def test_async_list_returns_a_plain_list():
     transport = FakeAsyncTransport(
         [api_pb2.ListVmsResponse(vms=[a_vm("alpha"), a_vm("beta")])]