boxd 0.2.10.dev609__tar.gz → 0.2.10.dev616__tar.gz

{boxd-0.2.10.dev609/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.dev609
+Version: 0.2.10.dev616
 Summary: Python SDK for the boxd cloud VM platform
 Author: Azin
 License-Expression: MIT
@@ -358,6 +358,7 @@ result.success     # bool
 
 boxd.machines.exec(id, ["echo", "a b"])              # a list is quoted for you
 boxd.machines.exec(id, "env", env={"FOO": "bar"})
+boxd.machines.exec(id, "make", cwd="/srv/app")       # run from a working directory
 boxd.machines.exec(id, "cargo build", timeout=30)    # seconds
 
 # Under a PTY, stderr merges into stdout and `stderr` comes back empty.
@@ -365,9 +366,22 @@ boxd.machines.exec(id, "top -b -n1", tty=True, cols=120, rows=40)
 ```
 
 `command` takes a list of argv — shell-quoted for you — or a ready-made command
-line as a string. `timeout` gives up on the call; whatever it started inside the
+line as a string. `cwd` runs the command from that directory; a `cwd` that
+doesn't exist fails fast instead of silently running in the default
+directory. `timeout` gives up on the call; whatever it started inside the
 machine may well still be running.
 
+**`result.stdout`/`result.stderr` are UTF-8-decoded with `errors="replace"`:**
+any byte sequence that isn't valid UTF-8 is silently replaced with `U+FFFD`,
+changing the length with no error raised. Fine for text output; corrupts
+binary output. For binary or byte-exact output, read from `stream_exec`
+instead — its chunks are raw `bytes`, never decoded:
+
+```python
+with boxd.machines.stream_exec(id, command="cat file.bin") as stream:
+    data = b"".join(stream)   # byte-exact
+```
+
 For anything interactive, `stream_exec` gives you a live session — the one
 handle in the SDK, because a bidirectional stream really is stateful:
 
@@ -420,13 +434,17 @@ from pathlib import Path
 
 written = boxd.machines.files.upload(id, "/app/config.json", '{"debug": true}')
 boxd.machines.files.upload(id, "/app/data.bin", Path("local.bin").read_bytes())
+boxd.machines.files.upload(id, "notes.txt", "relative to /home/boxd")
 data = boxd.machines.files.download(id, "/app/output.json")   # bytes
 ```
 
 `upload` takes `str` or `bytes`, streams it in chunks so large files are fine,
 and returns the number of bytes the machine confirmed it wrote. `download`
 streams too and returns the whole file as `bytes` — there is no size cap, but
-it is all held in memory.
+it is all held in memory. Paths are either absolute (`/app/config.json`) or
+relative to the VM user's home directory (`/home/boxd`) — a bare filename
+like `"notes.txt"` resolves to `/home/boxd/notes.txt`, same as `"./notes.txt"`
+or `"sub/notes.txt"` would.
 
 ### Ports and proxies
 
@@ -468,6 +486,16 @@ with one. `create` answers as soon as the route is accepted, so it confirms the
 subdomain and the port it was pointed at; `list()` reports the full domain and
 the resolved port.
 
+`port_mode="auto"` detection runs continuously for the whole life of the
+machine, not just once at boot: whenever the app binds one of a curated list
+of common ports (80, 443, 8080, 8000, 3000, 5000, 5173), that becomes a
+candidate, and it's adopted once roughly 750ms have passed with no *different*
+candidate port seen (an already-adopted port won't be replaced again more
+than once every 5s). So a redeploy or restart that moves your app onto a new
+port is picked up on its own within a few seconds — no action needed. If your
+app doesn't listen on one of those ports, or you don't want to wait out the
+detection window, call `set_port` with the port explicitly instead of `"auto"`.
+
 ### Checkpoints
 
 Per-machine captures, restored in place. They are deleted with the machine.

{boxd-0.2.10.dev609 → boxd-0.2.10.dev616}/README.md

@@ -326,6 +326,7 @@ result.success     # bool
 
 boxd.machines.exec(id, ["echo", "a b"])              # a list is quoted for you
 boxd.machines.exec(id, "env", env={"FOO": "bar"})
+boxd.machines.exec(id, "make", cwd="/srv/app")       # run from a working directory
 boxd.machines.exec(id, "cargo build", timeout=30)    # seconds
 
 # Under a PTY, stderr merges into stdout and `stderr` comes back empty.
@@ -333,9 +334,22 @@ boxd.machines.exec(id, "top -b -n1", tty=True, cols=120, rows=40)
 ```
 
 `command` takes a list of argv — shell-quoted for you — or a ready-made command
-line as a string. `timeout` gives up on the call; whatever it started inside the
+line as a string. `cwd` runs the command from that directory; a `cwd` that
+doesn't exist fails fast instead of silently running in the default
+directory. `timeout` gives up on the call; whatever it started inside the
 machine may well still be running.
 
+**`result.stdout`/`result.stderr` are UTF-8-decoded with `errors="replace"`:**
+any byte sequence that isn't valid UTF-8 is silently replaced with `U+FFFD`,
+changing the length with no error raised. Fine for text output; corrupts
+binary output. For binary or byte-exact output, read from `stream_exec`
+instead — its chunks are raw `bytes`, never decoded:
+
+```python
+with boxd.machines.stream_exec(id, command="cat file.bin") as stream:
+    data = b"".join(stream)   # byte-exact
+```
+
 For anything interactive, `stream_exec` gives you a live session — the one
 handle in the SDK, because a bidirectional stream really is stateful:
 
@@ -388,13 +402,17 @@ from pathlib import Path
 
 written = boxd.machines.files.upload(id, "/app/config.json", '{"debug": true}')
 boxd.machines.files.upload(id, "/app/data.bin", Path("local.bin").read_bytes())
+boxd.machines.files.upload(id, "notes.txt", "relative to /home/boxd")
 data = boxd.machines.files.download(id, "/app/output.json")   # bytes
 ```
 
 `upload` takes `str` or `bytes`, streams it in chunks so large files are fine,
 and returns the number of bytes the machine confirmed it wrote. `download`
 streams too and returns the whole file as `bytes` — there is no size cap, but
-it is all held in memory.
+it is all held in memory. Paths are either absolute (`/app/config.json`) or
+relative to the VM user's home directory (`/home/boxd`) — a bare filename
+like `"notes.txt"` resolves to `/home/boxd/notes.txt`, same as `"./notes.txt"`
+or `"sub/notes.txt"` would.
 
 ### Ports and proxies
 
@@ -436,6 +454,16 @@ with one. `create` answers as soon as the route is accepted, so it confirms the
 subdomain and the port it was pointed at; `list()` reports the full domain and
 the resolved port.
 
+`port_mode="auto"` detection runs continuously for the whole life of the
+machine, not just once at boot: whenever the app binds one of a curated list
+of common ports (80, 443, 8080, 8000, 3000, 5000, 5173), that becomes a
+candidate, and it's adopted once roughly 750ms have passed with no *different*
+candidate port seen (an already-adopted port won't be replaced again more
+than once every 5s). So a redeploy or restart that moves your app onto a new
+port is picked up on its own within a few seconds — no action needed. If your
+app doesn't listen on one of those ports, or you don't want to wait out the
+detection window, call `set_port` with the port explicitly instead of `"auto"`.
+
 ### Checkpoints
 
 Per-machine captures, restored in place. They are deleted with the machine.

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

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

{boxd-0.2.10.dev609 → 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.dev609 → boxd-0.2.10.dev616}/src/boxd/resources/machines.py

@@ -119,6 +119,7 @@ def _exec_init(
     tty: bool,
     cols: int,
     rows: int,
+    cwd: str | None = None,
 ) -> api_pb2.ExecChunk:
     """The first chunk of an `Exec` stream: command, PTY flags, geometry."""
     line = req.join_command(command)
@@ -127,6 +128,12 @@ def _exec_init(
         # shell, so prefix assignments do the job.
         prefix = " ".join(f"{k}={shlex.quote(v)}" for k, v in env.items())
         line = f"{prefix} {line}"
+    if cwd:
+        # Same reasoning as `env`: no cwd field on ExecChunk, so `cd` ahead of
+        # the command through the same shell. `&&` means a `cwd` that doesn't
+        # exist fails fast with `cd`'s own error instead of silently running
+        # in the default directory (BOX-292).
+        line = f"cd {shlex.quote(cwd)} && {line}"
     return req.exec_chunk(
         machine_id=machine_id, command=line, tty=tty, cols=cols, rows=rows
     )
@@ -151,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] = []
@@ -160,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:
@@ -473,27 +495,39 @@ class Machines(Namespace):
         command: str | Sequence[str],
         *,
         env: Mapping[str, str] | None = None,
+        cwd: str | None = None,
         tty: bool = False,
         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.
 
         With `tty` the command runs under a PTY, which merges stderr into
         stdout — `stderr` comes back empty and everything lands in `stdout`.
 
+        `cwd` runs the command in that directory; a `cwd` that doesn't exist
+        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
         it running with no one listening.
         """
         init = _exec_init(
-            machine_id, command, env=env, tty=tty, cols=cols, rows=rows
+            machine_id, command, env=env, tty=tty, cols=cols, rows=rows, cwd=cwd
         )
         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(
@@ -502,6 +536,7 @@ class Machines(Namespace):
         *,
         command: str | Sequence[str],
         env: Mapping[str, str] | None = None,
+        cwd: str | None = None,
         tty: bool = False,
         cols: int = 0,
         rows: int = 0,
@@ -514,7 +549,7 @@ class Machines(Namespace):
                 "a PTY shell needs stdin open"
             )
         init = _exec_init(
-            machine_id, command, env=env, tty=tty, cols=cols, rows=rows
+            machine_id, command, env=env, tty=tty, cols=cols, rows=rows, cwd=cwd
         )
         return ExecStream(self._transport, init, close_stdin=close_stdin)
 
@@ -1101,23 +1136,34 @@ class AsyncMachines(Namespace):
         command: str | Sequence[str],
         *,
         env: Mapping[str, str] | None = None,
+        cwd: str | None = None,
         tty: bool = False,
         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.
 
         With `tty` the command runs under a PTY, which merges stderr into
         stdout — `stderr` comes back empty and everything lands in `stdout`.
 
+        `cwd` runs the command in that directory; a `cwd` that doesn't exist
+        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
         it running with no one listening.
         """
         init = _exec_init(
-            machine_id, command, env=env, tty=tty, cols=cols, rows=rows
+            machine_id, command, env=env, tty=tty, cols=cols, rows=rows, cwd=cwd
         )
 
         async def once():
@@ -1132,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,
@@ -1144,6 +1186,7 @@ class AsyncMachines(Namespace):
         *,
         command: str | Sequence[str],
         env: Mapping[str, str] | None = None,
+        cwd: str | None = None,
         tty: bool = False,
         cols: int = 0,
         rows: int = 0,
@@ -1156,7 +1199,7 @@ class AsyncMachines(Namespace):
                 "a PTY shell needs stdin open"
             )
         init = _exec_init(
-            machine_id, command, env=env, tty=tty, cols=cols, rows=rows
+            machine_id, command, env=env, tty=tty, cols=cols, rows=rows, cwd=cwd
         )
         return AsyncExecStream(self._transport, init, close_stdin=close_stdin)
 

{boxd-0.2.10.dev609 → 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.dev609
+Version: 0.2.10.dev616
 Summary: Python SDK for the boxd cloud VM platform
 Author: Azin
 License-Expression: MIT
@@ -358,6 +358,7 @@ result.success     # bool
 
 boxd.machines.exec(id, ["echo", "a b"])              # a list is quoted for you
 boxd.machines.exec(id, "env", env={"FOO": "bar"})
+boxd.machines.exec(id, "make", cwd="/srv/app")       # run from a working directory
 boxd.machines.exec(id, "cargo build", timeout=30)    # seconds
 
 # Under a PTY, stderr merges into stdout and `stderr` comes back empty.
@@ -365,9 +366,22 @@ boxd.machines.exec(id, "top -b -n1", tty=True, cols=120, rows=40)
 ```
 
 `command` takes a list of argv — shell-quoted for you — or a ready-made command
-line as a string. `timeout` gives up on the call; whatever it started inside the
+line as a string. `cwd` runs the command from that directory; a `cwd` that
+doesn't exist fails fast instead of silently running in the default
+directory. `timeout` gives up on the call; whatever it started inside the
 machine may well still be running.
 
+**`result.stdout`/`result.stderr` are UTF-8-decoded with `errors="replace"`:**
+any byte sequence that isn't valid UTF-8 is silently replaced with `U+FFFD`,
+changing the length with no error raised. Fine for text output; corrupts
+binary output. For binary or byte-exact output, read from `stream_exec`
+instead — its chunks are raw `bytes`, never decoded:
+
+```python
+with boxd.machines.stream_exec(id, command="cat file.bin") as stream:
+    data = b"".join(stream)   # byte-exact
+```
+
 For anything interactive, `stream_exec` gives you a live session — the one
 handle in the SDK, because a bidirectional stream really is stateful:
 
@@ -420,13 +434,17 @@ from pathlib import Path
 
 written = boxd.machines.files.upload(id, "/app/config.json", '{"debug": true}')
 boxd.machines.files.upload(id, "/app/data.bin", Path("local.bin").read_bytes())
+boxd.machines.files.upload(id, "notes.txt", "relative to /home/boxd")
 data = boxd.machines.files.download(id, "/app/output.json")   # bytes
 ```
 
 `upload` takes `str` or `bytes`, streams it in chunks so large files are fine,
 and returns the number of bytes the machine confirmed it wrote. `download`
 streams too and returns the whole file as `bytes` — there is no size cap, but
-it is all held in memory.
+it is all held in memory. Paths are either absolute (`/app/config.json`) or
+relative to the VM user's home directory (`/home/boxd`) — a bare filename
+like `"notes.txt"` resolves to `/home/boxd/notes.txt`, same as `"./notes.txt"`
+or `"sub/notes.txt"` would.
 
 ### Ports and proxies
 
@@ -468,6 +486,16 @@ with one. `create` answers as soon as the route is accepted, so it confirms the
 subdomain and the port it was pointed at; `list()` reports the full domain and
 the resolved port.
 
+`port_mode="auto"` detection runs continuously for the whole life of the
+machine, not just once at boot: whenever the app binds one of a curated list
+of common ports (80, 443, 8080, 8000, 3000, 5000, 5173), that becomes a
+candidate, and it's adopted once roughly 750ms have passed with no *different*
+candidate port seen (an already-adopted port won't be replaced again more
+than once every 5s). So a redeploy or restart that moves your app onto a new
+port is picked up on its own within a few seconds — no action needed. If your
+app doesn't listen on one of those ports, or you don't want to wait out the
+detection window, call `set_port` with the port explicitly instead of `"auto"`.
+
 ### Checkpoints
 
 Per-machine captures, restored in place. They are deleted with the machine.

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

@@ -186,12 +186,36 @@ 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"})
     assert transport.sent[0].command == "MODE='a b' env"
 
 
+def test_exec_cwd_prepends_a_cd():
+    transport = FakeTransport([[api_pb2.ExecChunk(exit_code=0)]])
+    Machines(transport).exec("alpha", "pwd", cwd="/opt/my app")
+    assert transport.sent[0].command == "cd '/opt/my app' && pwd"
+
+
 def test_exec_reports_a_nonzero_exit():
     transport = FakeTransport([[api_pb2.ExecChunk(exit_code=3)]])
     result = Machines(transport).exec("alpha", "false")
@@ -666,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")])]