fcloud-sdk 0.1.0__py3-none-any.whl

fcloud/_legacy_env.py

@@ -0,0 +1,14 @@
+"""Map legacy ``FOOM_*`` environment variables onto their ``FCLOUD_*`` names.
+
+Imported first by the package so module-level reads (queue timeout, quiet
+mode, ...) already see the new names. ``FOOM_API_KEY``/``FOOM_URL`` are left
+to :mod:`fcloud.config`, whose .env-vs-export ranking must know which
+spelling a value arrived under.
+"""
+
+import os
+
+# ponytail: drop once nobody exports FOOM_* any more.
+for _k in [k for k in os.environ if k.startswith("FOOM_")]:
+    if _k not in ("FOOM_API_KEY", "FOOM_URL"):
+        os.environ.setdefault("FCLOUD_" + _k[len("FOOM_"):], os.environ[_k])

fcloud/cli/__init__.py

@@ -0,0 +1,23 @@
+"""fcloud CLI — GPU compute from the command line.
+
+Importing this package registers every command (each module below calls
+`registry.cmd` at import time); `fcloud.cli.main.main` dispatches them.
+Command modules mirror the `fcloud help` groups.
+"""
+
+from fcloud.cli import (  # noqa: F401 — imported for their registration side effects
+    exec_cmd,
+    files,
+    hardware,
+    interactive,
+    job,
+    mount,
+    processes,
+    run,
+    sessions,
+    setup,
+    ssh,
+    sweep,
+    volume,
+    wait,
+)

fcloud/cli/attach.py

@@ -0,0 +1,180 @@
+"""Attaching to an existing session, honestly and with retries.
+
+Terminal-state vocabulary, the attach retry schedule, the "session
+unreachable" exit and the Session handle every attach-style verb uses.
+"""
+
+import sys
+import time
+
+from fcloud.cli import output
+from fcloud.client import Client, PaymentOverdueError
+from fcloud.errors import VolumeConflictError, VolumeNotFoundError
+
+# Ride a restore for up to ~10 min — matches the dispatcher's
+# restorePhaseDeadline, so the client's patience tracks the server's, instead
+# of the old 300s reconnect budget vs 3600s run-timeout mismatch.
+_RESUME_BUDGET_S = 600.0
+
+
+# Authoritative session states that mean "do NOT resume": the session was
+# deliberately ended (stop), suspended, or died — or never existed at all
+# ("not_found", the dispatcher's 404). Reconnecting these would resurrect a
+# host the user/admin/billing already tore down.
+_TERMINAL_SESSION_STATES = {"closed", "closing", "dead", "failed", "not_found"}
+
+
+# States in which a session can never run its processes again. "closing" is
+# excluded: the host is still finalizing and its last process-index flush
+# (which records real exits) may not have landed yet — treating it as ended
+# would misreport a gracefully-stopped process as lost.
+_ENDED_SESSION_STATES = _TERMINAL_SESSION_STATES - {"closing"}
+
+
+# A fresh attach can fail transiently while the session is still binding to its
+# just-booted host (the setup window) or during a momentary control-plane blip.
+# Retry the attach on this short schedule before surfacing a failure — it
+# absorbs the first-exec-after-provision race without hanging on a dead session.
+_ATTACH_RETRY_DELAYS_S = (2.0, 5.0, 10.0)
+
+
+def _attach_with_retry(
+    client: Client, sid: str, volume_mounts, image_spec: str, sku: str,
+):
+    """Attach to a session, retrying a transient failure in the binding window.
+
+    Attach is idempotent (it only opens a data-plane WS), so retrying is safe —
+    unlike run(), which the caller issues exactly once. Bails out immediately if
+    the dispatcher says the session is terminal (closed/dead/failed): retrying
+    those would just wait out the schedule on a session that is never coming
+    back. The final failure re-raises so the caller can report the true cause.
+    """
+    last_exc: Exception | None = None
+    for delay in (0.0, *_ATTACH_RETRY_DELAYS_S):
+        if delay:
+            time.sleep(delay)
+        try:
+            return client.attach_session(
+                sid, volume_mounts=volume_mounts, image_spec=image_spec, sku=sku)
+        except PaymentOverdueError:
+            raise  # A billing suspension won't self-heal; surface it verbatim.
+        except (VolumeNotFoundError, VolumeConflictError):
+            # A bad --volume (typo'd name, mount conflict) is a user error;
+            # re-running the whole attach+resume schedule can't fix it.
+            raise
+        except Exception as exc:
+            last_exc = exc
+            if _authoritative_session_status(client, sid) in _TERMINAL_SESSION_STATES:
+                break
+    assert last_exc is not None
+    raise last_exc
+
+
+def _exit_session_unreachable(client: Client, sid: str, exc: Exception) -> None:
+    """Report an unreachable session honestly, then exit 75 (EX_TEMPFAIL).
+
+    The old code blamed every attach/run failure on a host migration ("being
+    restored on a new host"), which was usually false — the common case is a
+    transient blip while the session binds to its freshly-booted host. Consult
+    the dispatcher for the real status and describe *that*: a terminal session
+    is reported as ended, everything else as a retryable "not reachable yet".
+    Exit 75 either way so a polling caller retries, preserving prior behavior.
+    """
+    if isinstance(exc, (VolumeNotFoundError, VolumeConflictError)):
+        # The session is fine — the --volume request was wrong. Blaming
+        # session connectivity ("retry shortly") sends agents into a
+        # forever-retry loop on a permanent user error.
+        sys.stderr.write(f"Error: {exc}\n")
+        if output._JSON_OUTPUT:
+            output._out({"error": "volume", "detail": str(exc)})
+        sys.exit(2)
+    status = _authoritative_session_status(client, sid)
+    if status == "not_found":
+        # The dispatcher has no record of this session — say so instead of
+        # inventing a lifecycle ("has ended") for something that never lived.
+        msg = (f"session {sid} not found — check the ID; "
+               f"fcloud sessions --all lists your sessions")
+        sys.stderr.write(f"\033[33m⏳ {msg}\033[0m\n")
+        if output._JSON_OUTPUT:
+            output._out({"error": "not_found", "detail": str(exc)})
+        sys.exit(1)  # permanent — retrying can never succeed
+    if status in _TERMINAL_SESSION_STATES:
+        # An ended EPHEMERAL job can never come back (no persisted
+        # workspace) — a retry loop must stop, and the useful pointers are
+        # its durable outputs, not the session listing.
+        ephemeral = False
+        try:
+            ephemeral = client.describe_session(sid).ephemeral
+        except Exception:  # noqa: BLE001 — the hint is best-effort
+            pass
+        if ephemeral:
+            msg = (f"session {sid} was an ephemeral job and has ended "
+                   f"(status: {status}); it cannot be resumed. Durable "
+                   f"outputs: volumes (fcloud volume files <name>) and logs "
+                   f"(fcloud job logs {sid})")
+            sys.stderr.write(f"\033[33m⏳ {msg}\033[0m\n")
+            if output._JSON_OUTPUT:
+                output._out({"error": "ended", "detail": str(exc)})
+            sys.exit(1)  # permanent — retrying can never succeed
+        if status == "closed":
+            # Raw dispatcher status is "closed", but the user-facing warmth
+            # vocabulary (fcloud sessions) calls this "cold" — and unlike
+            # dead/failed it is not permanent: the session resumes on use.
+            detail, msg = "ended", (
+                f"session {sid} is cold (stopped, $0 — files kept); it comes "
+                f"back online the next time you run something on it. "
+                f"Inspect it with: fcloud sessions --all")
+        else:
+            detail, msg = "ended", (
+                f"session {sid} has ended (status: {status}); it is not "
+                f"reachable. Inspect it with: fcloud sessions --all")
+    else:
+        shown = f" (status: {status})" if status else ""
+        detail, msg = "unreachable", (
+            f"session {sid} is not reachable yet{shown} — it may be finishing "
+            "setup on its host, or its host may be migrating. Retry shortly.")
+    sys.stderr.write(f"\033[33m⏳ {msg}\033[0m\n")
+    if output._JSON_OUTPUT:
+        output._out({"error": detail, "detail": str(exc)})
+    sys.exit(75)  # EX_TEMPFAIL
+
+
+def _authoritative_session_status(client: Client, sid: str) -> str:
+    """Dispatcher-truth session status, used to gate a migration reconnect.
+
+    Returns the status string, "unreachable" for a transient 503, or "dead"
+    for a 404/410 Gone. Never raises — a gating read must not crash the run.
+    An indeterminate read returns "" (treated as non-terminal: prefer riding a
+    likely migration over abandoning it; the dispatcher GET rarely flaps).
+    The logic lives on Client.session_status so SDK users get the same map.
+    """
+    return client.session_status(sid)
+
+
+def _get_session_handle(client: Client, session_id: str, volume_mounts=None):
+    """Attach to an existing session and return a Session handle.
+
+    Returns (session, detach_fn). Call detach_fn() when done to
+    drop the WS without closing the session. ``volume_mounts`` attaches
+    volumes at the same time (spawn parity with exec's --volume); it
+    defaults to None so the other verbs attach unchanged.
+
+    Attaches with the same retry schedule as `exec`, so verbs like
+    `spawn`/`upload` ride the setup-binding blip and the seconds-scale
+    auto-close window instead of dying on a raw dispatcher error. A
+    session that still can't be reached is reported honestly (ended vs
+    retryable) and exits 75 — never a bare `HTTP 410` or
+    `session_not_requeueable`.
+
+    ``volume_mounts`` are applied on attach the same way `exec` applies
+    them, so `spawn --volume` mounts a volume for the process it starts.
+    """
+    try:
+        session = _attach_with_retry(client, session_id, volume_mounts, "", "")
+    except PaymentOverdueError:
+        # Billing suspension is not "unreachable" — let main()'s dedicated
+        # handler explain the suspended account and exit 3, not 75.
+        raise
+    except Exception as exc:
+        _exit_session_unreachable(client, session_id, exc)
+    return session, lambda: client.detach_session(session_id)

fcloud/cli/common.py

@@ -0,0 +1,382 @@
+"""Shared argv helpers: flag extraction, unit parsing, session-id rules.
+
+Pure functions over `list[str]` argv slices; no network, no config.
+"""
+
+import os
+import sys
+
+from fcloud.config import dotenv_value
+from fcloud.fileset import UploadOptions
+
+
+def _extract_flag(args: list[str], flag: str) -> tuple[str, list[str]]:
+    """Pull a --flag VALUE from args, return (value, remaining_args).
+
+    Rejects two easy mistakes with a precise error instead of letting a
+    malformed value flow downstream as a mystery `session_not_found` (or a
+    dropped command): the flag repeated, or its value being flag-shaped —
+    e.g. `--on --on s-abc` binds `--on`'s value to the literal "--on" and
+    silently drops the real id.
+    """
+    if args.count(flag) > 1:
+        raise ValueError(f"{flag} specified more than once")
+    value = ""
+    rest = []
+    i = 0
+    while i < len(args):
+        if args[i] == flag:
+            if i + 1 >= len(args):
+                raise ValueError(f"{flag} expects a value")
+            candidate = args[i + 1]
+            if candidate.startswith("--"):
+                raise ValueError(
+                    f"{flag} expects a value, but got '{candidate}' "
+                    "(looks like a flag)")
+            value = candidate
+            i += 2
+        else:
+            rest.append(args[i])
+            i += 1
+    return value, rest
+
+
+def _extract_bool_flag(args: list[str], flag: str) -> tuple[bool, list[str]]:
+    """Pull a standalone --flag out of args, return (present, remaining)."""
+    present = flag in args
+    return present, [a for a in args if a != flag]
+
+
+def _split_trailing_args(args: list[str]) -> tuple[list[str], list[str]]:
+    if "--" not in args:
+        return args, []
+    split = args.index("--")
+    return args[:split], args[split + 1:]
+
+
+def _looks_like_session_id(value: str) -> bool:
+    return value.startswith("s-")
+
+
+def _consume_positional_session(args: list[str]) -> tuple[str, list[str]]:
+    if args and _looks_like_session_id(args[0]):
+        return args[0], args[1:]
+    return "", args
+
+
+def _resolve_session_and_rest(args: list[str]) -> tuple[str, list[str]]:
+    """Resolve a session id from either --on SID or a leading positional SID,
+    returning (sid, remaining_args). Mirrors how exec/run/shell accept the
+    session, so upload/download take it the same way (consistency papercut)."""
+    on_sid, rest = _extract_on(args)
+    if not on_sid:
+        on_sid, rest = _consume_positional_session(rest)
+    return on_sid, rest
+
+
+def _extract_sku(args: list[str]) -> tuple[str, list[str]]:
+    return _extract_flag(args, "--sku")
+
+
+def _extract_on(args: list[str]) -> tuple[str, list[str]]:
+    return _extract_flag(args, "--on")
+
+
+def _extract_wait(args: list[str]) -> tuple[int, list[str]]:
+    value, rest = _extract_flag(args, "--wait")
+    if not value:
+        value, rest = _extract_flag(rest, "--timeout")
+    return _parse_duration_seconds(value or "30s"), rest
+
+
+def _parse_duration_seconds(value: str) -> int:
+    value = value.strip().lower()
+    if value in ("0", "none", "forever"):
+        return 0
+    multipliers = {
+        "s": 1,
+        "m": 60,
+        "h": 60 * 60,
+        "d": 24 * 60 * 60,
+    }
+    suffix = value[-1]
+    if suffix in multipliers:
+        return int(float(value[:-1]) * multipliers[suffix])
+    return int(float(value))
+
+
+def _parse_byte_count(value: str) -> int:
+    value = value.strip().lower()
+    multipliers = {
+        "b": 1,
+        "k": 1024,
+        "kb": 1024,
+        "m": 1024 * 1024,
+        "mb": 1024 * 1024,
+        "g": 1024 * 1024 * 1024,
+        "gb": 1024 * 1024 * 1024,
+    }
+    for suffix in ("gb", "kb", "mb", "g", "k", "m", "b"):
+        if value.endswith(suffix):
+            return int(float(value[: -len(suffix)]) * multipliers[suffix])
+    return int(float(value))
+
+
+def _parse_keep_warm(spec: str) -> int:
+    """Parse --keep-warm SECONDS into a non-negative int."""
+    try:
+        seconds = int(spec)
+    except ValueError:
+        raise ValueError(f"--keep-warm expects a number of seconds, got {spec!r}") from None
+    if seconds < 0:
+        raise ValueError("--keep-warm seconds must be >= 0")
+    return seconds
+
+
+# Hosts default to a 256 GiB root volume; the largest satisfiable request
+# (a 10 TiB volume + headroom) stays well under 16 TiB. Anything above that
+# would queue a session no provider can ever place.
+_MIN_DISK_GB_MAX = 16384
+
+
+def _parse_min_disk(spec: str) -> int:
+    """Parse --min-disk-gb GiB into a bounded positive int."""
+    try:
+        gb = int(spec)
+    except ValueError:
+        raise ValueError(
+            f"--min-disk-gb expects a whole number of GiB, got {spec!r}") from None
+    if gb < 1:
+        raise ValueError(
+            "--min-disk-gb must be >= 1 (omit the flag for the 256 GiB default)")
+    if gb > _MIN_DISK_GB_MAX:
+        raise ValueError(
+            f"--min-disk-gb {gb} exceeds the {_MIN_DISK_GB_MAX} GiB (16 TiB) "
+            "ceiling — no host can be provisioned that large")
+    return gb
+
+
+def _reject_volume_upload_collision(volume_mounts, local) -> None:
+    """Refuse a --volume mount that collides with an upload target.
+
+    run/job uploads land at /workspace/<name>. A volume mounted at that
+    same path would be silently shadowed by the upload, and the uploaded
+    files committed into the volume on close — volume pollution with no
+    error anywhere (BUG-1, 2026-08-20 report). Same for a mount below the
+    upload dir when the local tree has content at that subpath. A mount
+    below the upload dir over an EMPTY local subpath stays allowed: it
+    composes cleanly, and writes into it are ordinary volume writes.
+    """
+    dest = f"/workspace/{local.name}"
+    for mount in volume_mounts:
+        name = mount.get("name", "")
+        mpath = mount.get("mount_path") or f"/workspace/{name}"
+        mpath = "/" + mpath.strip("/")
+        if mpath == dest:
+            print(
+                f"Error: volume_mount_target_not_empty — volume {name!r} "
+                f"mounts at {mpath}, exactly where the upload places "
+                f"{local.name!r}. The upload would shadow the volume and "
+                "be committed into it on close. Mount the volume at a "
+                f"different path (--volume {name}:/workspace/{name}) or "
+                "rename the upload.",
+                file=sys.stderr)
+            sys.exit(2)
+        if local.is_dir() and mpath.startswith(dest + "/"):
+            sub = local.joinpath(*mpath[len(dest) + 1:].split("/"))
+            if sub.is_file() or (sub.is_dir() and any(sub.iterdir())):
+                print(
+                    f"Error: volume_mount_target_not_empty — volume "
+                    f"{name!r} mounts at {mpath}, but the upload already "
+                    f"has content at {sub}. Those files would shadow the "
+                    "volume and be committed into it on close. Move them "
+                    "or mount the volume elsewhere.",
+                    file=sys.stderr)
+                sys.exit(2)
+
+
+def _warn_sku_ignored_on_attach(client, sid: str, sku: str) -> None:
+    """`--sku` with `--on` only takes effect when a COLD session resumes
+    (the resume re-provisions on the requested SKU). Against a live session
+    it is silently ignored — say so. Best-effort: never blocks the attach."""
+    if not sku:
+        return
+    try:
+        info = client.describe_session(sid)
+    except Exception:  # noqa: BLE001 — a hint must not break the attach
+        return
+    if info.sku and info.sku != sku and info.status == "active":
+        print(
+            f"Warning: --sku {sku} ignored — session {sid} is already "
+            f"running on {info.sku}. --sku applies only when a cold session "
+            "resumes; create a new session to change hardware.",
+            file=sys.stderr)
+
+
+def _extract_min_disk(args: list[str]) -> tuple[int, list[str]]:
+    """Pull --min-disk-gb (alias --min-disk) N out of args; 0 if absent."""
+    rest: list[str] = []
+    val = 0
+    i = 0
+    while i < len(args):
+        if args[i] in ("--min-disk-gb", "--min-disk") and i + 1 < len(args):
+            val = _parse_min_disk(args[i + 1])
+            i += 2
+        else:
+            rest.append(args[i])
+            i += 1
+    return val, rest
+
+
+def _extract_output_policy(args: list[str]) -> tuple[str, int | None, list[str]]:
+    output_range = "tail"
+    output_limit: int | None = 64 * 1024
+    rest: list[str] = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg in ("--output", "--stdout") and i + 1 < len(args):
+            output_range = args[i + 1].lower()
+            i += 2
+        elif arg in ("--output-bytes", "--stdout-bytes") and i + 1 < len(args):
+            output_limit = _parse_byte_count(args[i + 1])
+            i += 2
+        elif arg in ("--no-output-limit", "--stdout-all"):
+            output_range = "all"
+            output_limit = None
+            i += 1
+        else:
+            rest.append(arg)
+            i += 1
+    if output_range == "all":
+        output_limit = None
+    if output_range not in ("all", "head", "middle", "tail"):
+        raise ValueError("--output must be one of: all, head, middle, tail")
+    return output_range, output_limit, rest
+
+
+def _extract_upload_options(args: list[str]) -> tuple[UploadOptions, list[str]]:
+    """Pull `--include-hidden` / `--follow-symlinks` out of args.
+
+    Directory uploads skip hidden entries (.env, .git, .venv …) and symlinked
+    files by default — see fcloud.fileset. These flags are the explicit opt-in.
+    """
+    opts = UploadOptions()
+    rest: list[str] = []
+    for a in args:
+        if a == "--include-hidden":
+            opts.include_hidden = True
+        elif a == "--follow-symlinks":
+            opts.follow_symlinks = True
+        else:
+            rest.append(a)
+    return opts, rest
+
+
+def _extract_volumes(args: list[str]) -> tuple[list[dict[str, str]], list[str]]:
+    mounts: list[dict[str, str]] = []
+    rest: list[str] = []
+    i = 0
+    while i < len(args):
+        if args[i] == "--volume" and i + 1 < len(args):
+            mounts.append(_parse_volume_mount(args[i + 1]))
+            i += 2
+        else:
+            rest.append(args[i])
+            i += 1
+    return mounts, rest
+
+
+def _parse_volume_mount(spec: str) -> dict[str, str]:
+    name, sep, mount = spec.partition(":")
+    name = name.strip()
+    if not name:
+        raise ValueError("--volume requires NAME[:MOUNT]")
+    out = {"name": name}
+    if sep:
+        out["mount_path"] = mount.strip()
+    return out
+
+
+def _extract_secrets(args: list[str]) -> tuple[dict[str, str], list[str]]:
+    """Pull repeatable `--secret KEY[=VALUE]` flags out of args.
+
+    Secrets are injected into the session's *runtime* env only — they never
+    touch fcloud.json (which is committed to git), so tokens like HF_TOKEN stay
+    out of version control. `--secret KEY=VALUE` sets the value inline;
+    `--secret KEY` inherits KEY from the caller's own environment, or —
+    failing that — from the nearest .env file. Naming the key is the opt-in:
+    a .env's non-fcloud entries never enter this process's environment.
+    """
+    secrets: dict[str, str] = {}
+    rest: list[str] = []
+    i = 0
+    while i < len(args):
+        if args[i] == "--secret" and i + 1 < len(args):
+            key, sep, value = args[i + 1].partition("=")
+            key = key.strip()
+            if not key:
+                raise ValueError("--secret requires KEY[=VALUE]")
+            if sep:
+                secrets[key] = value
+            elif key in os.environ:
+                secrets[key] = os.environ[key]
+            elif (dotenv := dotenv_value(key)) is not None:
+                secrets[key] = dotenv
+            else:
+                raise ValueError(
+                    f"--secret {key}: no value given and {key} is unset in the "
+                    f"environment and the nearest .env (use --secret {key}=VALUE)")
+            i += 2
+        else:
+            rest.append(args[i])
+            i += 1
+    return secrets, rest
+
+
+def _shape_exec_command(cmd_args: list[str]) -> list[str]:
+    """Keep argv commands structured, but treat one CLI string as shell text."""
+    if len(cmd_args) == 1:
+        return ["bash", "-lc", cmd_args[0]]
+    return cmd_args
+
+
+def _print_upload_summary(result: dict, *, verb: str = "Uploaded") -> None:
+    """One line on stderr: what the host wrote and what the policy skipped.
+
+    Reports the count the HOST acknowledged, not the local file count — they
+    differ exactly when the pull went wrong, and printing the local count hid
+    that. The skip note names the flag that would include each class.
+    """
+    written = result.get("written", 0)
+    total = result.get("bytes_total", 0)
+    line = f"{verb} {written} file(s), {total} bytes"
+    note = result.get("skip_note") or ""
+    if note:
+        line += f" — {note}"
+    print(line, file=sys.stderr)
+    _print_s3_route(result)
+
+
+def _print_s3_route(result: dict) -> None:
+    """Name the files that took the presigned-S3 route, if any.
+
+    Files above the inline threshold leave the WS and go client→S3→host,
+    which is a different path with different failure modes. Printing it
+    always (not only on failure) is what makes "the upload broke" traceable
+    to a file — one oversized results JSON in an otherwise tiny code upload
+    silently routes the batch through S3.
+    """
+    large = result.get("s3_files") or []
+    if not large:
+        return
+    threshold = int(result.get("s3_threshold_bytes", 0))
+    limit_mib = threshold // (1 << 20) if threshold else 0
+    print(f"  {len(large)} file(s) over {limit_mib} MiB took the S3 "
+          f"upload path (client → S3 → host):", file=sys.stderr)
+    for entry in large[:5]:
+        size_mb = int(entry.get("size", 0)) / 1e6
+        print(f"    {entry.get('path', '')}  ({size_mb:.1f} MB)",
+              file=sys.stderr)
+    if len(large) > 5:
+        print(f"    … +{len(large) - 5} more", file=sys.stderr)