flashnode 0.2.1__tar.gz → 0.3.1__tar.gz

{flashnode-0.2.1 → flashnode-0.3.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: flashnode
-Version: 0.2.1
+Version: 0.3.1
 Summary: Open host agent for the FlashML fragmented-compute network: join, benchmark, execute sandboxed ML tasks, earn contribution credits.
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/Zolli-Labs/flashnode
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flashruntime<0.4,>=0.3
+Requires-Dist: flashruntime<0.5,>=0.4
 Requires-Dist: psutil>=5.9
 Requires-Dist: websockets>=12
 Requires-Dist: cryptography>=42
@@ -49,10 +49,27 @@ verified results. Two profiles:
   inside managed pools (DaemonSet); KubeRay owns workload pods there.
   Implemented.
 
+## Check your machine first
+
+```bash
+flashnode doctor
+```
+
+Six checks: the `docker` CLI, the engine behind it, an anonymous pull of a
+curated image, whether a container can see your work directory, whether your
+Docker accepts the sandbox flags, and whether any directories you lend via
+`FLASHNODE_LOCAL_DATA` are readable. Every failure names the fix.
+
+Run it once before `flashnode work`. `work` repeats all of it **except** the
+image pull — a registry blip should not stop an agent whose images are
+already cached — and refuses to start if anything fails, because a host that
+cannot run tasks should not be claiming them.
+
 ## What it does today
 
 ```bash
 pip install -e .                      # plus: pip install -e ../flashruntime
+flashnode doctor                      # check this machine can run tasks
 flashnode work --coordinator http://<coordinator>:8100
 # optional hardening / pool config:
 #   FLASHNODE_JOIN_CODE=...          join-code-gated pools
@@ -60,8 +77,17 @@ flashnode work --coordinator http://<coordinator>:8100
 #   FLASHNODE_WORKDIR=$HOME/.cache/flashnode   (macOS + colima: VM-visible workdirs)
 #   FLASHNODE_WORKDIR=C:\Users\<you>\.flashnode  (Windows: must be under a
 #                                                 directory Docker Desktop shares)
+#   FLASHNODE_LOCAL_DATA=patients=/srv/data/patients-2026,labs=/srv/labs
+#                                    lend local directories to tasks by LABEL
 ```
 
+`FLASHNODE_LOCAL_DATA` lets you offer data **without uploading it**. Only the
+label names (`patients`, `labs`) are advertised to the coordinator — never the
+paths — and a task that names a label in its `local_inputs` gets that directory
+bind-mounted **read-only** at `/work/inputs/<label>`. A task asking for a label
+this machine does not lend is refused, not run half-fed; a task that asks for
+nothing sees nothing, exactly as before.
+
 If the coordinator enforces per-machine authentication
 (`FLASHML_NODE_TOKENS` set server-side), save the bearer token you were
 given before running `work`:

{flashnode-0.2.1 → flashnode-0.3.1}/README.md

@@ -32,10 +32,27 @@ verified results. Two profiles:
   inside managed pools (DaemonSet); KubeRay owns workload pods there.
   Implemented.
 
+## Check your machine first
+
+```bash
+flashnode doctor
+```
+
+Six checks: the `docker` CLI, the engine behind it, an anonymous pull of a
+curated image, whether a container can see your work directory, whether your
+Docker accepts the sandbox flags, and whether any directories you lend via
+`FLASHNODE_LOCAL_DATA` are readable. Every failure names the fix.
+
+Run it once before `flashnode work`. `work` repeats all of it **except** the
+image pull — a registry blip should not stop an agent whose images are
+already cached — and refuses to start if anything fails, because a host that
+cannot run tasks should not be claiming them.
+
 ## What it does today
 
 ```bash
 pip install -e .                      # plus: pip install -e ../flashruntime
+flashnode doctor                      # check this machine can run tasks
 flashnode work --coordinator http://<coordinator>:8100
 # optional hardening / pool config:
 #   FLASHNODE_JOIN_CODE=...          join-code-gated pools
@@ -43,8 +60,17 @@ flashnode work --coordinator http://<coordinator>:8100
 #   FLASHNODE_WORKDIR=$HOME/.cache/flashnode   (macOS + colima: VM-visible workdirs)
 #   FLASHNODE_WORKDIR=C:\Users\<you>\.flashnode  (Windows: must be under a
 #                                                 directory Docker Desktop shares)
+#   FLASHNODE_LOCAL_DATA=patients=/srv/data/patients-2026,labs=/srv/labs
+#                                    lend local directories to tasks by LABEL
 ```
 
+`FLASHNODE_LOCAL_DATA` lets you offer data **without uploading it**. Only the
+label names (`patients`, `labs`) are advertised to the coordinator — never the
+paths — and a task that names a label in its `local_inputs` gets that directory
+bind-mounted **read-only** at `/work/inputs/<label>`. A task asking for a label
+this machine does not lend is refused, not run half-fed; a task that asks for
+nothing sees nothing, exactly as before.
+
 If the coordinator enforces per-machine authentication
 (`FLASHML_NODE_TOKENS` set server-side), save the bearer token you were
 given before running `work`:

{flashnode-0.2.1 → flashnode-0.3.1}/flashnode/agent/cli.py

@@ -26,6 +26,7 @@ commands:
             (--coordinator URL; --token TOKEN to skip the browser step)
   logout    remove the saved bearer token for a FlashRuntime coordinator
             (--coordinator URL)
+  doctor    check this machine can run tasks (docker engine, images, mounts)
   join      connect this machine to a FlashML control plane (not yet implemented)
   status    show node identity, capabilities, and active leases (not yet implemented)
   leave     drain and disconnect (not yet implemented)
@@ -201,10 +202,27 @@ def _work(args: list[str]) -> int:
         # (subprocess.run(["docker", ...])); if it isn't installed that call
         # raises FileNotFoundError deep inside a task attempt. Check for it
         # here, at startup, rather than let the agent die on the first task.
-        if shutil.which("docker") is None:
+        # A `docker` binary on PATH says nothing about the daemon behind it,
+        # the credential helper Docker consults when it pulls, or whether
+        # this machine's work directory is even visible inside the VM. Both
+        # hosts that stopped the 2026-08-02 §10 run-through passed the old
+        # `shutil.which` check and then failed every task they claimed —
+        # docker_runner raises TaskExecutionError, loop.py calls fail() and
+        # claims the next one, forever, silently.
+        #
+        # pull=False deliberately: an agent is a long-running daemon on
+        # someone else's machine, and a transient registry blip must not
+        # stop one whose images are already cached. `flashnode doctor` does
+        # the pull.
+        from flashnode.doctor import format_results, run_checks
+
+        results = run_checks(pull=False)
+        if any(r.status != "ok" for r in results):
             print(
-                f"flashnode work: --runner {opts.runner} requires the `docker` CLI "
-                "on PATH — refusing to start without it",
+                f"flashnode work: this machine cannot run tasks with "
+                f"--runner {opts.runner}.\n" + format_results(results)
+                + "\n\nRun `flashnode doctor` for the full check, including "
+                  "the image pull this skipped.",
                 file=sys.stderr,
             )
             return 2
@@ -270,6 +288,10 @@ def main(argv: list[str] | None = None) -> int:
         return agent_main()
     if args and args[0] == "work":
         return _work(args[1:])
+    if args and args[0] == "doctor":
+        from flashnode.doctor import doctor_main
+
+        return doctor_main(args[1:])
     if args and args[0] == "login":
         return _login(args[1:])
     if args and args[0] == "logout":

flashnode-0.3.1/flashnode/config/local_data.py

@@ -0,0 +1,111 @@
+"""Local datasets: data the host owner lends to tasks without uploading it.
+
+    FLASHNODE_LOCAL_DATA="patients=/srv/data/patients-2026,labs=/srv/labs"
+
+The owner names a directory on their machine and gives it a LABEL. The label
+is what the agent advertises to the coordinator (`NodeRegistration.
+local_datasets`, so the placement gate can route a job that needs `patients`
+to a machine that has it); the PATH never leaves this machine. That asymmetry
+is the feature — a path leaks the owner's directory layout, their username,
+and frequently the dataset's identity, and none of that is needed to schedule
+work.
+
+Two rules make the rest of the system safe to write:
+
+- **Fail closed on garbage** (same judgement as `HostPolicy` above): a
+  malformed value raises rather than yielding the entries that happened to
+  parse. Half-applying the owner's intent is the worst outcome — they believe
+  two directories are exposed, one is, and the disagreement surfaces hours
+  later as a job that never places.
+- **A label is a name, not a path fragment.** It is restricted to
+  ``[A-Za-z0-9._-]`` here, once, so that no consumer downstream has to defend
+  itself: it is a map key, and a single container-side directory segment. If
+  someone later joins it to a host path, the charset already forbids the
+  escape.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+__all__ = ["LocalDataError", "LABEL_RE", "check_label", "parse_local_data",
+           "load_local_data", "LOCAL_DATA_ENV"]
+
+LOCAL_DATA_ENV = "FLASHNODE_LOCAL_DATA"
+
+#: The whole alphabet a dataset label may use. Deliberately narrower than
+#: anything a filesystem accepts: '/', '..' and whitespace are the characters
+#: that turn a name into a traversal, and they are simply not expressible.
+LABEL_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+class LocalDataError(ValueError):
+    """The owner's `FLASHNODE_LOCAL_DATA` cannot be honoured as written."""
+
+
+def check_label(label: str) -> str:
+    """Return `label` if it is a legal dataset label; raise otherwise.
+
+    Shared by the parser (owner-supplied labels) and the mount builder
+    (payload-supplied labels) so both ends of the wire agree on what a label
+    is — one definition, not two that can drift.
+    """
+    if not LABEL_RE.match(label) or label in (".", ".."):
+        raise LocalDataError(
+            f"illegal local dataset label {label!r}: labels are names, not "
+            "paths — use only [A-Za-z0-9._-]"
+        )
+    return label
+
+
+def parse_local_data(raw: str | None) -> dict[str, str]:
+    """Parse ``"label=/path,other=/path2"`` into ``{label: path}``.
+
+    Unset, empty, or all-separators means the owner did not opt in, and that
+    is the normal case: an empty map, no mounts, nothing advertised.
+    """
+    result: dict[str, str] = {}
+    for entry in (raw or "").split(","):
+        entry = entry.strip()
+        if not entry:
+            continue
+        label, sep, path = entry.partition("=")
+        label, path = label.strip(), path.strip()
+        if not sep or not label or not path:
+            raise LocalDataError(
+                f"malformed {LOCAL_DATA_ENV} entry {entry!r}: expected "
+                "label=/absolute/path"
+            )
+        check_label(label)
+        if not path.startswith("/") and ":" not in path:
+            # A relative path would resolve against whatever directory the
+            # agent happens to have been started in — never what the owner
+            # meant, and a moving target between a shell run and a systemd
+            # unit. (The ':' escape hatch is a Windows drive letter, which
+            # the next check then judges on its own terms.)
+            raise LocalDataError(
+                f"local dataset {label!r} path {path!r} is not absolute — "
+                "refusing to resolve it against the agent's working directory"
+            )
+        if ":" in path and not re.match(r"^[A-Za-z]:[\\/]", path):
+            # `docker -v` splits its argument on ':'. A source containing one
+            # silently re-reads as src:dst:opts — i.e. as a mount the owner
+            # did not write. A Windows drive letter is the one form that is
+            # both legitimate and rewritable (hardening._bind_mount_source).
+            raise LocalDataError(
+                f"local dataset {label!r} path {path!r} contains ':', which "
+                "cannot be used as a bind-mount source"
+            )
+        if label in result:
+            raise LocalDataError(
+                f"local dataset label {label!r} is mapped twice — refusing to "
+                "guess which directory the owner meant"
+            )
+        result[label] = path
+    return result
+
+
+def load_local_data(env: dict[str, str] | None = None) -> dict[str, str]:
+    """The host owner's dataset map, from the environment."""
+    return parse_local_data((env if env is not None else os.environ).get(LOCAL_DATA_ENV))