letify 2.10.0__tar.gz → 2.10.1__tar.gz

{letify-2.10.0 → letify-2.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: letify
-Version: 2.10.0
+Version: 2.10.1
 Summary: Declarations that become infrastructure.
 Project-URL: Homepage, https://github.com/DarkPyonix/letify
 Project-URL: Documentation, https://github.com/DarkPyonix/letify/tree/main/docs

{letify-2.10.0 → letify-2.10.1}/docs/SPEC.md

@@ -1333,7 +1333,7 @@ connection, but a call's second large blob is split whenever splitting is faster
 
 A connection that costs something to open has to pay for itself, so a provider reports `transfer_connection_cost_s`, the seconds one more connection takes. It is 0 for a provider that dials an address, and about 10 for one reached by a hole punch, because that is what a punch measures. The streams are opened only when the transfer is expected to finish sooner with them: the estimate uses the probe's upload rate, assumes the streams scale and that their connections are opened at the same time, and keeps one stream when `size / (rate x streams) + cost` is not less than `size / rate`. A measured case: a Kaggle runtime at a 44.7 ms round trip carried 128 MiB at 21.0 MiB/s on one stream and 9.5 MiB/s on four, 2.2 times worse, because three more punches cost more than the transfer saved. The same account at a 193 ms round trip carried 1.57 MiB/s on one raw SSH connection and 6.10 MiB/s on four, so the gain is real where the link is slow enough and the blob large enough for it to be worth 10 s.
 
-The connections have to be real ones. Every SSH command letify builds carries `ControlMaster=auto`, which multiplexes further sessions onto the first connection, so opening more channels that way would add streams inside one TCP connection and gain nothing. A transfer channel therefore sets `ControlPath=none` and `ControlMaster=no`, and a punched link gives each its own socket, so each transfer channel is its own kernel connection. A punched link holds the spare sockets of its punch, `PUNCH_SOCKETS` of them in all, [Rendezvous](#rendezvous), and hands one to each SSH command before it redials. The worker channel and the first transfer channels therefore cost no rendezvous, and `transfer_connection_cost_s` applies only to the streams beyond the spares.
+The connections have to be real ones. Every SSH command letify builds carries `ControlMaster=auto`, which multiplexes further sessions onto the first connection, so opening more channels that way would add streams inside one TCP connection and gain nothing. A transfer channel therefore sets `ControlPath=none` and `ControlMaster=no`, and a punched link gives each its own socket, so each transfer channel is its own kernel connection. A punched link holds the spare sockets of its punch, `PUNCH_SOCKETS` of them in all, [Rendezvous](#rendezvous), and hands one to each SSH command before it redials. The worker channel and the first transfer channels therefore cost no rendezvous, and `transfer_connection_cost_s` applies only to the streams beyond the spares: with `k` spares still unused and `s` streams wanted, `s - 1 - k` punches are needed, and when that is above 0 the estimate adds the cost once (the punches run at the same time), otherwise it adds 0. The link reports `k` as `spare_connections()`, which is 0 for every link but a punched one.
 
 The worker's `data_put` appends to one handle per digest and hashes as it goes, which assumes the pieces arrive in order on one stream. Parallel senders cannot use it, so they use two other requests:
 
@@ -2683,6 +2683,11 @@ The worker records the first failure and skips the operators after it until a sy
 
 A lost worker process or link raises `RuntimeLost`, and the session is discarded.
 
+An executor that ends because of an exception sends one last message, a failure naming the exception, before it stops, so the client stops waiting at once instead of waiting for a reply that cannot come. This holds at startup and in the middle of a session, on the call worker's channel and as a process of its own. The client discards the executor and raises:
+
+- `ConfigError` when the executor could not start because a module is missing from the runtime's environment, such as `torch`. The message names the exception, for example `ModuleNotFoundError: No module named 'torch'`, and for `torch` says to add it to the project's dependencies. It is not retried, because a fresh runtime builds the same environment from the same lock.
+- `RuntimeLost`, carrying the executor's exception and traceback, for any other exception.
+
 ### Version guards <!-- id: forwarding-versions -->
 
 > PyTorch 2.1 or newer is required locally and on the runtime.

{letify-2.10.0 → letify-2.10.1}/letify/__init__.py

@@ -70,7 +70,7 @@ distributed: Final = Host.distributed
 # The enum class stays importable from letify.declare.instance for letify's own use.
 del Host
 
-__version__ = "2.10.0"
+__version__ = "2.10.1"
 
 
 def fetch(tensor):  # type: ignore[no-untyped-def]

{letify-2.10.0 → letify-2.10.1}/letify/remoting/device/client.py

@@ -29,7 +29,7 @@ from typing import Any
 import torch
 from blake3 import blake3
 
-from ...errors import RemoteError, RuntimeLost
+from ...errors import ConfigError, RemoteError, RuntimeLost
 from .executor import E_DEFINE, E_OP, E_REQUEST, E_STEP, E_STEP_DEFINE, UPLOAD_CACHE_BYTES
 from .frames import ChannelTransport, StreamTransport, Transport, TransportClosed
 from .guard import check_torch_version, check_worker_version
@@ -279,6 +279,7 @@ class Client:
         """Read the executor's first message, check its PyTorch, and start the threads."""
         head, _buffers = self._recv()
         self.hello = pickle.loads(head)
+        self._raise_fatal(self.hello)
         check_worker_version(local=torch.__version__, remote=str(self.hello["torch"]))
         self._sender = threading.Thread(
             target=self._send_loop, name=f"{self.name}-send", daemon=True
@@ -811,6 +812,7 @@ class Client:
         head, buffers = self._recv()
         consumers = self._replies.popleft()
         reply = pickle.loads(head)
+        self._raise_fatal(reply)
         results = reply["results"]
         failure = reply.get("failure")
         for note in reply.get("notes", ()):
@@ -1016,6 +1018,25 @@ class Client:
         detail = f"\n--- device worker stderr ---\n{tail}" if tail else ""
         return RuntimeLost(f"{self.name}: the device worker was lost: {reason}{detail}")
 
+    def _raise_fatal(self, message: dict) -> None:
+        """Raise the failure an executor sent as its last message, discarding the executor."""
+        fatal = message.get("fatal")
+        if fatal is None:
+            return
+        error = fatal["error"]
+        if fatal["started"] or fatal["missing"] is None:
+            where = "the device executor stopped" if fatal["started"] else "could not start"
+            lost = self._lose(f"{where}: {error}\n{fatal['traceback']}")
+            raise lost
+        self._lose(error)
+        hint = (
+            "; add torch to the project's dependencies (uv add torch) so the runtime's "
+            "environment has it"
+            if fatal["missing"] == "torch"
+            else "; add it to the project's dependencies"
+        )
+        raise ConfigError(f"{self.name}: the device executor could not start: {error}{hint}")
+
     def _check_open(self) -> None:
         if os.getpid() != self._pid:
             raise RuntimeLost(
@@ -1113,10 +1134,10 @@ def connect(
 
         transport.raw(count_line(source) + source)
         client.start()
-    except (TransportClosed, RuntimeLost) as exc:
+    except (TransportClosed, RuntimeLost, ConfigError) as exc:
         process.kill()
         process.wait()
-        if isinstance(exc, RuntimeLost):
+        if isinstance(exc, (RuntimeLost, ConfigError)):
             raise
         raise client._lose(str(exc)) from exc
     return client
@@ -1132,7 +1153,11 @@ def attach(
     channel.request(
         {"op": "device", "device": device, "source": worker_source(None).decode()}, timeout=600
     )
-    client.start()
+    try:
+        client.start()
+    except (RuntimeLost, ConfigError):
+        transport.close()
+        raise
     return client
 
 

{letify-2.10.0 → letify-2.10.1}/letify/remoting/device/executor.py

@@ -946,14 +946,37 @@ class Executor:
 
 
 def serve_transport(device: str, transport) -> None:
-    """Announce the executor on ``transport`` and answer its messages until it closes."""
-    executor = Executor(device)
-    transport.send(pickle.dumps(executor.hello(), protocol=5), [])
-    while True:
+    """Announce the executor on ``transport`` and answer its messages until it closes.
+
+    An exception that ends the executor is sent as a last message, so the client stops
+    waiting for a reply that cannot come, as spec "Failure semantics" describes.
+    """
+    started = False
+    try:
+        executor = Executor(device)
+        transport.send(pickle.dumps(executor.hello(), protocol=5), [])
+        started = True
+        _answer(executor, transport)
+    except TransportClosed:
+        return
+    except BaseException as exc:
+        detail = traceback.format_exc()
+        print(detail, file=sys.stderr, flush=True)
+        fatal = {
+            "error": f"{type(exc).__name__}: {exc}",
+            "traceback": detail,
+            "started": started,
+            "missing": exc.name if isinstance(exc, ImportError) else None,
+        }
         try:
-            head, buffers = transport.recv()
-        except TransportClosed:
-            return
+            transport.send(pickle.dumps({"fatal": fatal}, protocol=5), [])
+        except Exception:  # pragma: no cover - the link is gone as well
+            pass
+
+
+def _answer(executor: Executor, transport) -> None:
+    while True:
+        head, buffers = transport.recv()
         message = pickle.loads(head)
         head = None
         if message.get("close"):
@@ -962,10 +985,7 @@ def serve_transport(device: str, transport) -> None:
         buffers = None
         if reply is not None:
             reply_head, views, keep = reply
-            try:
-                transport.send(reply_head, views)
-            except TransportClosed:
-                return
+            transport.send(reply_head, views)
             del keep
 
 

{letify-2.10.0 → letify-2.10.1}/letify/store/pathdata.py

@@ -1096,6 +1096,7 @@ def streams_for(
     size: int,
     rate_bps: float | None = None,
     cost_s: float = 0.0,
+    spares: int = 0,
 ) -> int:
     """How many connections this blob is worth splitting across.
 
@@ -1103,14 +1104,16 @@ def streams_for(
     connections to send a few megabytes costs more than it saves; one on a short link,
     because there a single stream already carries everything the link will carry; never
     more streams than there are chunks to send; and, when a connection costs something to
-    open, only as many as finish the transfer sooner than one would.
+    open, only as many as finish the transfer sooner than one would. The extra streams
+    (all but one) that the link's ``spares`` cover cost nothing, so the cost applies only
+    when ``count - 1`` exceeds them.
     """
     if streams <= 1 or size < threshold_mib * (1 << 20):
         return 1
     if rtt_ms is None or rtt_ms < PARALLEL_RTT_MS:
         return 1
     count = max(1, min(streams, (size + CHUNK - 1) // CHUNK))
-    if cost_s > 0 and count > 1:
+    if cost_s > 0 and count - 1 > max(0, spares):
         if not rate_bps or rate_bps <= 0:
             # Nothing to weigh the cost against, and the cost is real, so do not pay it.
             return 1
@@ -1147,6 +1150,15 @@ def _measured_rtt(provider: Any, runtime: Any) -> float | None:
     return getattr(_measured_link(provider, runtime), "rtt_ms", None)
 
 
+def _spares_of(link: Any) -> int:
+    """The spare connections ``link`` still holds, 0 where it has no such query."""
+    query = getattr(link, "spare_connections", None)
+    try:
+        return max(0, int(query())) if callable(query) else 0
+    except Exception:
+        return 0
+
+
 def _streams_for(runtime: Any, size: int, *, warm: bool = False) -> int:
     """``streams_for`` with the account's settings and the link's measured round trip.
 
@@ -1167,6 +1179,7 @@ def _streams_for(runtime: Any, size: int, *, warm: bool = False) -> int:
         threshold_mib=int(getattr(provider, "transfer_parallel_mib", PARALLEL_MIB) or 0),
         rate_bps=rate,
         cost_s=cost_s,
+        spares=_spares_of(link),
         rtt_ms=rtt,
         size=size,
     )

{letify-2.10.0 → letify-2.10.1}/letify/transport/link.py

@@ -44,6 +44,10 @@ class Link:
         """A stream the probe can run over, or None when this link cannot carry it."""
         return None
 
+    def spare_connections(self) -> int:
+        """Connections handed out with no rendezvous. Spec "Several connections at once"."""
+        return 0
+
     def ssh_command(self, remote_command: str | None = None) -> list[str]:
         raise RuntimeFailure(f"the {self.strategy} link carries no SSH session")
 
@@ -150,6 +154,11 @@ class PunchedLink(Link):
                 sock = self._spares.pop(0)
         return sock if sock is not None else self._redial()
 
+    def spare_connections(self) -> int:
+        """The spare sockets of the punch that no SSH command has taken yet."""
+        with self._lock:
+            return len(self._spares)
+
     def ssh_command(self, remote_command: str | None = None) -> list[str]:
         listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         # Port 0: the operating system chooses, because Windows reserves ranges per machine.

{letify-2.10.0 → letify-2.10.1}/letify-core/Cargo.lock

@@ -138,11 +138,11 @@ dependencies = [
 
 [[package]]
 name = "letify"
-version = "2.10.0"
+version = "2.10.1"
 
 [[package]]
 name = "letify-quic"
-version = "2.10.0"
+version = "2.10.1"
 dependencies = [
  "quinn",
  "rcgen",

{letify-2.10.0 → letify-2.10.1}/letify-core/Cargo.toml

@@ -8,7 +8,7 @@ resolver = "3"
 members = ["letify", "letify-quic"]
 
 [workspace.package]
-version = "2.10.0"
+version = "2.10.1"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/DarkPyonix/letify"

{letify-2.10.0 → letify-2.10.1}/letify-ext/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "letify-status",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "letify-status",
-      "version": "2.10.0",
+      "version": "2.10.1",
       "license": "SEE LICENSE IN LICENSE",
       "devDependencies": {
         "@types/node": "^18.19.0",

{letify-2.10.0 → letify-2.10.1}/letify-ext/package.json

@@ -2,7 +2,7 @@
   "name": "letify-status",
   "displayName": "letify Status",
   "description": "letify quota and GPU activity in the status bar, read from the letify CLI.",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "publisher": "darkpyonix",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

{letify-2.10.0 → letify-2.10.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "letify"
-version = "2.10.0"
+version = "2.10.1"
 description = "Declarations that become infrastructure."
 readme = "README.md"
 requires-python = ">=3.11"

{letify-2.10.0 → letify-2.10.1}/tests/test_device.py

@@ -2027,3 +2027,114 @@ def test_the_environment_variable_turns_the_automatic_behaviour_off(monkeypatch)
     monkeypatch.delenv("LETIFY_AUTO_FETCH")
     assert auto_fetch_enabled(False) is False
     assert auto_fetch_enabled(None) is True
+
+
+# -- Spec: Failure semantics ---------------------------------------------------------
+
+
+class _Loopback:
+    """The client's end of a pair of queues whose other end is ``serve_transport``."""
+
+    def __init__(self, incoming, outgoing):
+        self.incoming = incoming
+        self.outgoing = outgoing
+
+    def send(self, head, buffers) -> None:
+        self.outgoing.put((bytes(head), [bytes(b) for b in buffers]))
+
+    def recv(self):
+        message = self.incoming.get(timeout=20)
+        if message is None:
+            raise frames.TransportClosed("the loopback closed")
+        return message
+
+    def close(self) -> None:
+        self.outgoing.put(None)
+
+
+def _serve_in_thread(monkeypatch, make_executor):
+    """Run the real ``serve_transport`` in a thread and return the client on its other end."""
+    import queue
+    import threading
+
+    from letify.remoting.device import executor as executor_module
+
+    requests, replies = queue.Queue(), queue.Queue()
+    monkeypatch.setattr(executor_module, "Executor", make_executor)
+    server = _Loopback(requests, replies)
+    thread = threading.Thread(
+        target=executor_module.serve_transport,
+        args=("cpu", server),
+        daemon=True,
+    )
+    thread.start()
+    return forwarding.Client(_Loopback(replies, requests), name="loopback"), thread
+
+
+def test_a_device_executor_that_dies_mid_session_fails_the_waiting_read(monkeypatch) -> None:
+    from letify.remoting.device import executor as executor_module
+
+    real = executor_module.Executor
+
+    class Dying(real):
+        def run(self, message, buffers):
+            raise ValueError("the executor broke")
+
+    client, thread = _serve_in_thread(monkeypatch, Dying)
+    client.start()
+    with client.activate(), pytest.raises(letify.RuntimeLost, match="the executor broke"):
+        torch.ones(2, device="cuda").cpu()
+    thread.join(5)
+    assert not thread.is_alive()
+
+
+def test_a_device_executor_that_cannot_start_fails_the_hello_naming_the_cause(
+    monkeypatch,
+) -> None:
+    class Broken:
+        def __init__(self, device):
+            raise RuntimeError("no device to start on")
+
+    client, _thread = _serve_in_thread(monkeypatch, Broken)
+    with pytest.raises(letify.RuntimeLost, match="no device to start on"):
+        client.start()
+
+
+_WITHOUT_TORCH = (
+    "import sys\n"
+    "class _NoTorch:\n"
+    "    def find_spec(self, name, path=None, target=None):\n"
+    "        if name == 'torch':\n"
+    "            raise ModuleNotFoundError(\"No module named 'torch'\", name='torch')\n"
+    "sys.meta_path.insert(0, _NoTorch())\n"
+)
+
+
+def test_a_device_worker_that_cannot_import_torch_fails_the_call_naming_it(
+    let, cpu, monkeypatch
+) -> None:
+    from letify.remoting.device import client as client_module
+
+    real = client_module.worker_source
+    future_line = b"from __future__ import annotations\n"
+
+    def without_torch(device):
+        return real(device).replace(future_line, future_line + _WITHOUT_TORCH.encode(), 1)
+
+    monkeypatch.setattr(client_module, "worker_source", without_torch)
+
+    @let.function(device=cpu, host="local")
+    def step() -> float:
+        return float(torch.ones(2, device="cuda").sum().item())
+
+    # The call must fail at once instead of waiting for a reply that never comes.
+    import concurrent.futures
+
+    pool = concurrent.futures.ThreadPoolExecutor(1)
+    try:
+        future = pool.submit(step)
+        with pytest.raises(letify.ConfigError, match="No module named 'torch'") as caught:
+            future.result(timeout=60)
+    finally:
+        pool.shutdown(wait=False)
+    assert "add torch" in str(caught.value).lower() or "dependencies" in str(caught.value)

{letify-2.10.0 → letify-2.10.1}/tests/test_parallel_placement.py

@@ -548,3 +548,82 @@ class _Measured:
     def __init__(self, rtt_ms: float, upload_bps: float) -> None:
         self.rtt_ms = rtt_ms
         self.upload_bps = upload_bps
+
+
+def test_spare_sockets_let_a_transfer_open_streams_without_paying_a_punch() -> None:
+    """Spec "Several connections at once": streams covered by spares cost no rendezvous.
+
+    128 MiB at 56.8 MiB/s takes 2.3 s, so a 10 s punch keeps one stream. With three
+    spares the three extra streams of a four stream split need no punch and are kept.
+    """
+    from letify.store.pathdata import streams_for
+
+    MIB = 1 << 20
+    near = dict(streams=4, threshold_mib=64, rtt_ms=44.7, size=128 * MIB, rate_bps=56.8 * MIB)
+    assert streams_for(**near, cost_s=10.0, spares=0) == 1
+    assert streams_for(**near, cost_s=10.0, spares=3) == 4
+    assert streams_for(**near, cost_s=10.0, spares=4) == 4
+
+
+def test_streams_beyond_the_spares_pay_the_connection_cost() -> None:
+    """Spec: with fewer spares than extra streams, one punch is paid, once, for all of them."""
+    from letify.store.pathdata import streams_for
+
+    MIB = 1 << 20
+    near = dict(streams=4, threshold_mib=64, rtt_ms=44.7, size=128 * MIB, rate_bps=56.8 * MIB)
+    assert streams_for(**near, cost_s=10.0, spares=2) == 1
+    far = dict(streams=4, threshold_mib=64, rtt_ms=193.0, size=1024 * MIB, rate_bps=12.8 * MIB)
+    assert streams_for(**far, cost_s=10.0, spares=2) == 4
+
+
+def test_a_punched_link_reports_the_spare_sockets_it_still_holds() -> None:
+    """Spec: a punched link holds the spares of its punch; any other link holds none."""
+    import socket
+
+    from letify.transport.link import Link, PunchedLink
+
+    assert Link("x", 0).spare_connections() == 0
+    pairs = [socket.socketpair() for _ in range(4)]
+    socks = [a for a, _ in pairs]
+    link = PunchedLink("tcp_punch", 0, socks[0], lambda port, cmd: [], lambda: socks[0], socks[1:])
+    try:
+        assert link.spare_connections() == 3
+        link._take()  # the punched connection itself
+        assert link.spare_connections() == 3
+        link._take()  # first spare
+        assert link.spare_connections() == 2
+    finally:
+        link.close()
+        for _, b in pairs:
+            b.close()
+
+
+def test_the_placement_reads_the_spares_from_the_link(monkeypatch) -> None:
+    """Spec: `_streams_for` passes the link's spare count, so a Kaggle shard splits for free."""
+    from conftest import provider_of
+
+    from letify.providers import Kaggle
+    from letify.store.pathdata import _streams_for
+
+    MIB = 1 << 20
+    provider = provider_of(Kaggle, "kaggle_a")
+
+    class Runtime:
+        name = "letify-t4-cd14ab"
+
+    def make(spares: int):
+        class Link:
+            strategy = "tcp_punch"
+            rtt_ms = 44.7
+            upload_bps = 56.8 * MIB
+
+            def spare_connections(self) -> int:
+                return spares
+
+        return Link()
+
+    Runtime.provider = provider
+    provider._links[Runtime.name] = make(0)
+    assert _streams_for(Runtime(), 128 * MIB) == 1
+    provider._links[Runtime.name] = make(3)
+    assert _streams_for(Runtime(), 128 * MIB) == 4