boxd 0.2.10__tar.gz → 0.2.10.dev615__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.2.10
+Version: 0.2.10.dev615
 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 → boxd-0.2.10.dev615}/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 → boxd-0.2.10.dev615}/pyproject.toml

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

{boxd-0.2.10 → boxd-0.2.10.dev615}/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
     )
@@ -473,6 +480,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,
@@ -483,13 +491,17 @@ class Machines(Namespace):
         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.
+
         `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(
@@ -502,6 +514,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 +527,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,6 +1114,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,
@@ -1111,13 +1125,17 @@ class AsyncMachines(Namespace):
         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.
+
         `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():
@@ -1144,6 +1162,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 +1175,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 → boxd-0.2.10.dev615/src/boxd.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.2.10
+Version: 0.2.10.dev615
 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 → boxd-0.2.10.dev615}/tests/test_namespaces.py

@@ -192,6 +192,12 @@ def test_exec_prefixes_env_assignments():
     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")