fvpnctl 0.2.2__tar.gz → 0.2.3__tar.gz

{fvpnctl-0.2.2 → fvpnctl-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fvpnctl
-Version: 0.2.2
+Version: 0.2.3
 Summary: Control your FortiClient VPN from the macOS command line.
 Project-URL: Homepage, https://github.com/mpasternak/fortivpn-cli
 Project-URL: Repository, https://github.com/mpasternak/fortivpn-cli
@@ -224,6 +224,9 @@ Global options:
 - `--verbose` / `--quiet` — progress messages. Verbose is **on by default** and writes
   progress to **stderr**; `--quiet` silences it. Either way `stdout` carries only the
   machine-readable result, so `--json` output and shell pipelines are byte-identical.
+  While `connect` waits for the tunnel (it polls once a second), verbose mode shows a
+  Braille throbber with an elapsed-seconds counter on a TTY, falls back to a single
+  static line when stderr is piped or redirected, and shows nothing under `--quiet`.
 
 `list` and `status` additionally accept `--json` for machine-readable output.
 

{fvpnctl-0.2.2 → fvpnctl-0.2.3}/README.md

@@ -200,6 +200,9 @@ Global options:
 - `--verbose` / `--quiet` — progress messages. Verbose is **on by default** and writes
   progress to **stderr**; `--quiet` silences it. Either way `stdout` carries only the
   machine-readable result, so `--json` output and shell pipelines are byte-identical.
+  While `connect` waits for the tunnel (it polls once a second), verbose mode shows a
+  Braille throbber with an elapsed-seconds counter on a TTY, falls back to a single
+  static line when stderr is piped or redirected, and shows nothing under `--quiet`.
 
 `list` and `status` additionally accept `--json` for machine-readable output.
 

{fvpnctl-0.2.2 → fvpnctl-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fvpnctl"
-version = "0.2.2"
+version = "0.2.3"
 requires-python = ">=3.11"
 readme = "README.md"
 description = "Control your FortiClient VPN from the macOS command line."

{fvpnctl-0.2.2 → fvpnctl-0.2.3}/src/fvpnctl/__init__.py

@@ -1,3 +1,3 @@
 """fvpnctl — control FortiClient IPsec VPN on macOS via the Chrome DevTools Protocol."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"

{fvpnctl-0.2.2 → fvpnctl-0.2.3}/src/fvpnctl/cli.py

@@ -67,6 +67,7 @@ from fvpnctl import launcher, monitor
 from fvpnctl.cdp import CDPSession
 from fvpnctl.controller import FortiVPN
 from fvpnctl.errors import CDPEvaluateError, FortiError, NotRunningError
+from fvpnctl.spinner import Spinner
 
 # IPsec ``ipsec_state`` value meaning "tunnel up" (docs/how-it-works.md section 2
 # / design spec 4.2). The CLI only needs the CONNECTED sentinel; the controller
@@ -364,20 +365,31 @@ def _cmd_connect(fvpnctl: FortiVPN, args: argparse.Namespace) -> int:
     and returns; otherwise, on a CONNECTED terminal state, it fetches the VPN IP
     and prints ``CONNECTED <profile> <ip>``. The password is resolved inside the
     controller (from the Keychain) and is never accepted or printed here.
+
+    The waited path blocks in the controller's once-a-second poll loop while the
+    daemon negotiates, which otherwise looks frozen — so it is wrapped in a
+    :class:`~fvpnctl.spinner.Spinner` that animates a Braille throbber on stderr
+    (a single static line when piped, nothing under ``--quiet``; gated by
+    ``_VERBOSE`` exactly like :func:`report`). ``--no-wait`` returns immediately,
+    so it keeps the plain progress line instead.
     """
     wait = not args.no_wait
-    report(f"Connecting profile {args.profile}…")
-    state = fvpnctl.connect(
-        args.profile,
-        username=args.user,
-        wait=wait,
-        timeout=args.timeout,
-    )
+    msg = f"Connecting profile {args.profile}…"
 
     if not wait:
+        report(msg)
+        fvpnctl.connect(args.profile, username=args.user, wait=False, timeout=args.timeout)
         print(f"connecting {args.profile} ...")
         return 0
 
+    with Spinner(msg, stream=sys.stderr, enabled=_VERBOSE):
+        state = fvpnctl.connect(
+            args.profile,
+            username=args.user,
+            wait=True,
+            timeout=args.timeout,
+        )
+
     if state.ipsec_state == _CONNECTED:
         ip = fvpnctl.connection_ip(args.profile, _IPSEC)
         vpn_ip = ip.get("vpn_ip", "")

fvpnctl-0.2.3/src/fvpnctl/spinner.py

@@ -0,0 +1,156 @@
+"""Connect throbber — a Braille spinner for the blocking ``connect`` wait.
+
+Why this exists
+---------------
+``fvpnctl connect <profile>`` (without ``--no-wait``) blocks in
+:meth:`FortiVPN._wait_for_connection`, which polls ``getConnectionState`` once a
+second for up to ``--timeout`` seconds while the daemon negotiates the IPsec
+tunnel. That loop is silent, so a slow handshake looks like a frozen process.
+This module paints a live Braille spinner + elapsed-seconds counter so the user
+can see the wait is *working*, not hung.
+
+How it stays out of the controller's way
+----------------------------------------
+The poll loop lives in ``controller.py`` and must stay UI-agnostic (the same
+controller/transport/render split the rest of the codebase follows — see
+``monitor.py``). So the spinner does **not** reach into the loop: the CLI wraps
+the blocking ``connect()`` call in a :class:`Spinner` context manager, the
+spinner animates on a daemon thread while the main thread does the CDP I/O, and
+``__exit__`` tears the animation down. The controller is untouched.
+
+Three modes, chosen from the stream + verbosity (:func:`select_mode`)
+---------------------------------------------------------------------
+* **off**    — ``--quiet`` (``enabled=False``): write nothing at all.
+* **static** — verbose but the stream is not a TTY (piped / redirected): one
+  plain ``message`` line, no ANSI and no ``\\r`` spam, so logs stay readable.
+* **animate**— verbose on a real TTY: hide the cursor, paint frame 0
+  synchronously (instant first feedback, and one deterministic frame for tests),
+  then animate the remaining frames on a background thread until ``__exit__``.
+
+stderr, never stdout
+--------------------
+Like ``cli.report``, the spinner writes to **stderr** so stdout stays the
+machine-readable channel (``CONNECTED <profile> <ip>``, ``--json``, pipelines).
+``__exit__`` wipes the spinner line and restores the cursor *before* the caller
+prints its result/error, so success and failure both start on a clean line.
+
+Pure vs. I/O
+------------
+:func:`render_frame` and :func:`select_mode` are pure (data in, string out) and
+unit-tested directly; only :class:`Spinner` touches a stream, a thread, and the
+clock.
+"""
+
+import itertools
+import sys
+import threading
+import time
+
+# Braille "dots" spinner — ten frames that read as a smooth rotation. Zero
+# dependencies (project rule): the frames are just literal Unicode here.
+_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+# ANSI control sequences (defined locally so this module stays standalone, like
+# ``monitor.py`` keeps its own copy). Named so the I/O below reads as intent.
+_HIDE_CURSOR = "\x1b[?25l"
+_SHOW_CURSOR = "\x1b[?25h"
+_CLEAR_EOL = "\x1b[K"
+
+
+def render_frame(frame: str, message: str, elapsed: int) -> str:
+    """Build one spinner line: ``\\r<frame> <message>  <elapsed>s`` + clear-to-EOL.
+
+    Leads with ``\\r`` so each frame overwrites the previous one in place, and
+    ends with :data:`_CLEAR_EOL` so a shrinking ``message`` (or a smaller elapsed
+    count) never leaves stale characters trailing on the line. Pure — no I/O.
+    """
+    return f"\r{frame} {message}  {elapsed:d}s{_CLEAR_EOL}"
+
+
+def select_mode(stream, *, enabled: bool) -> str:
+    """Choose ``off``/``static``/``animate`` from verbosity + the stream.
+
+    ``enabled`` is the CLI's verbose flag: ``False`` (``--quiet``) → ``off``
+    regardless of the stream. Otherwise a real TTY animates and anything else
+    (a pipe, a file, a captured test buffer) gets the single static line.
+    """
+    if not enabled:
+        return "off"
+    isatty = getattr(stream, "isatty", None)
+    if isatty and isatty():
+        return "animate"
+    return "static"
+
+
+class Spinner:
+    """Context manager that animates a Braille throbber around a blocking call.
+
+    Usage::
+
+        with Spinner("Connecting profile apoz…", stream=sys.stderr, enabled=verbose):
+            state = fvpnctl.connect(...)   # blocks; the spinner animates meanwhile
+
+    The mode is fixed at construction from ``stream`` + ``enabled`` (see
+    :func:`select_mode`). In ``animate`` mode a daemon thread paints a frame
+    every ``interval`` seconds; ``__exit__`` stops it, joins it, wipes the line
+    and restores the cursor — including when the wrapped block raises (a
+    ``ConnectTimeout``/``ConnectFailed`` must still leave a clean terminal).
+    """
+
+    def __init__(self, message: str, *, stream=None, enabled: bool = True, interval: float = 0.1):
+        self._message = message
+        self._stream = stream if stream is not None else sys.stderr
+        self._interval = interval
+        self._mode = select_mode(self._stream, enabled=enabled)
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._start: float | None = None
+
+    def __enter__(self) -> "Spinner":
+        if self._mode == "off":
+            return self
+        if self._mode == "static":
+            # Pipe/log path: one plain line, no animation. Mirrors the old
+            # ``report("Connecting profile …")`` behaviour exactly.
+            self._stream.write(self._message + "\n")
+            self._stream.flush()
+            return self
+        # animate: hide the cursor and paint the first frame right away so there
+        # is instant feedback (and one deterministic frame for the tests) before
+        # the background thread takes over.
+        self._start = time.monotonic()
+        self._stream.write(_HIDE_CURSOR)
+        self._paint(_FRAMES[0])
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        return self
+
+    def _paint(self, frame: str) -> None:
+        """Write one frame for the current elapsed time, then flush."""
+        elapsed = int(time.monotonic() - self._start) if self._start is not None else 0
+        self._stream.write(render_frame(frame, self._message, elapsed))
+        self._stream.flush()
+
+    def _run(self) -> None:
+        """Background loop: advance the frame every ``interval`` until stopped.
+
+        Uses ``Event.wait(interval)`` rather than ``time.sleep`` so ``__exit__``
+        setting the stop event ends the wait *immediately* — the spinner never
+        delays the caller by up to ``interval`` on teardown.
+        """
+        for frame in itertools.cycle(_FRAMES[1:] + _FRAMES[:1]):
+            if self._stop.wait(self._interval):
+                return
+            self._paint(frame)
+
+    def __exit__(self, *exc) -> bool:
+        if self._mode != "animate":
+            return False
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join()
+        # Wipe the spinner line and bring the cursor back so the caller's next
+        # write (result on stdout / error on stderr) starts on a clean line.
+        self._stream.write("\r" + _CLEAR_EOL + _SHOW_CURSOR)
+        self._stream.flush()
+        return False  # never suppress the wrapped block's exception

fvpnctl-0.2.3/tests/test_spinner.py

@@ -0,0 +1,110 @@
+"""Tests for the connect throbber (``fvpnctl.spinner``).
+
+CI-safe: no real terminal, no real sleeping that the suite depends on. The pure
+helpers (:func:`spinner.render_frame`, :func:`spinner.select_mode`) are tested
+directly. The :class:`spinner.Spinner` context manager is driven over a fake
+stream whose ``isatty()`` is scripted, so each of the three modes
+(``off``/``static``/``animate``) is exercised deterministically:
+
+* ``off``   — ``enabled=False`` (the ``--quiet`` path): writes nothing.
+* ``static``— a non-TTY stream (pipe/log): one plain line, no ANSI, no ``\\r``.
+* ``animate``— a TTY stream: hides the cursor, paints frame 0 *synchronously* on
+  enter (so at least one frame is deterministic without waiting on the thread),
+  and on exit wipes the line and restores the cursor.
+
+The animate test uses a deliberately huge ``interval`` so the background thread
+is still parked in its first ``wait`` when ``__exit__`` sets the stop event —
+that makes "exactly the synchronous frame 0 was painted" reliable rather than
+racing the thread's clock.
+"""
+
+import io
+
+from fvpnctl import spinner
+
+
+class FakeStream(io.StringIO):
+    """A ``StringIO`` with a scripted ``isatty()`` so mode selection is testable."""
+
+    def __init__(self, *, tty):
+        super().__init__()
+        self._tty = tty
+
+    def isatty(self):
+        return self._tty
+
+
+# -- pure helpers ------------------------------------------------------------
+
+
+def test_render_frame_carries_braille_message_and_elapsed():
+    out = spinner.render_frame("⠋", "Connecting profile apoz…", 7)
+    assert out.startswith("\r")
+    assert "⠋" in out
+    assert "Connecting profile apoz…" in out
+    assert "7s" in out
+    # Clears to end of line so a shrinking message never leaves stale tail chars.
+    assert out.endswith(spinner._CLEAR_EOL)
+
+
+def test_select_mode_off_when_disabled_even_on_tty():
+    assert spinner.select_mode(FakeStream(tty=True), enabled=False) == "off"
+
+
+def test_select_mode_static_on_non_tty():
+    assert spinner.select_mode(FakeStream(tty=False), enabled=True) == "static"
+
+
+def test_select_mode_animate_on_tty():
+    assert spinner.select_mode(FakeStream(tty=True), enabled=True) == "animate"
+
+
+# -- context manager: the three modes ----------------------------------------
+
+
+def test_off_mode_writes_nothing():
+    stream = FakeStream(tty=True)
+    with spinner.Spinner("Connecting profile apoz…", stream=stream, enabled=False):
+        pass
+    assert stream.getvalue() == ""
+
+
+def test_static_mode_writes_one_plain_line():
+    stream = FakeStream(tty=False)
+    with spinner.Spinner("Connecting profile apoz…", stream=stream, enabled=True):
+        pass
+    out = stream.getvalue()
+    assert out == "Connecting profile apoz…\n"
+    # No ANSI, no carriage-return animation in the pipe/log path.
+    assert "\x1b" not in out
+    assert "\r" not in out
+
+
+def test_animate_mode_paints_frame0_and_cleans_up():
+    stream = FakeStream(tty=True)
+    # Huge interval: the worker thread parks in its first wait() and never paints
+    # a second frame before __exit__ stops it — so only the synchronous frame 0
+    # is guaranteed, making the assertions deterministic.
+    with spinner.Spinner("Connecting profile apoz…", stream=stream, enabled=True, interval=1000):
+        pass
+    out = stream.getvalue()
+    assert spinner._HIDE_CURSOR in out  # cursor hidden on enter
+    assert spinner._FRAMES[0] in out  # first braille frame painted synchronously
+    assert "Connecting profile apoz…" in out
+    assert spinner._SHOW_CURSOR in out  # cursor restored on exit
+    # The line is wiped on exit so the next print starts clean.
+    assert out.rstrip().endswith(spinner._SHOW_CURSOR) or spinner._CLEAR_EOL in out
+
+
+def test_animate_mode_restores_cursor_even_on_exception():
+    stream = FakeStream(tty=True)
+    try:
+        with spinner.Spinner(
+            "Connecting profile apoz…", stream=stream, enabled=True, interval=1000
+        ):
+            raise RuntimeError("connect blew up")
+    except RuntimeError:
+        pass
+    out = stream.getvalue()
+    # A failed connect (ConnectTimeout etc.) must still leave a clean terminal.
+    assert spinner._SHOW_CURSOR in out

{fvpnctl-0.2.2 → fvpnctl-0.2.3}/uv.lock

@@ -12,7 +12,7 @@ supported-markers = [
 
 [[package]]
 name = "fvpnctl"
-version = "0.2.2"
+version = "0.2.3"
 source = { editable = "." }
 
 [package.dev-dependencies]