mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/outlets/connect.py

@@ -0,0 +1,249 @@
+"""Connect a destination with one click, then pick where its results go (docs/webhooks.mdx)."""
+
+import logging
+import threading
+import time
+import uuid
+
+from ..api_errors import APIError
+from ..connectors import oauth, shared
+from ..connectors import presets as preset_list
+from . import net
+from .kinds import again
+from .webhook import Outcome
+
+log = logging.getLogger("mobster.outlets")
+
+KEEP_SECONDS = 900.0
+MAX_CONNECTS = 8
+SLACK_OFF = "Mobster's connectors aren't running, and a Slack destination posts with Slack's. Restart Mobster."
+GONE = "That sign-in ran out. Connect again."
+
+
+class Connect:
+    def __init__(self, kind, at):
+        self.id, self.kind, self.at = uuid.uuid4().hex[:12], kind, at
+        self.state, self.message, self.found, self.flow = "waiting", None, None, None
+        self.connector = None         # Slack: the connector whose sign-in this waits for
+
+    def public(self):
+        found = self.found or {}
+        return {"id": self.id, "kind": self.kind.id, "state": self.state, "message": self.message,
+                "account": found.get("account"), "targets": found.get("targets")}
+
+
+class Connects:
+    """The connects in flight and finished, for one OutletService."""
+
+    def __init__(self, *, call, connectors, apps=None, sign_in=oauth.SignIn, clock=time.monotonic):
+        self.call, self.connectors, self.clock = call, connectors, clock
+        self.apps = apps if apps is not None else shared.Apps()
+        self.sign_in_class = sign_in
+        self._items = {}
+        self._lock = threading.Lock()
+
+    def offered(self, kind):
+        """Whether Connect can add a destination of ``kind`` now, so the app lists it only then: Slack when a Slack
+        connector is signed in already, or when Settings offers the Slack connector (presets.offered: a gated preset
+        once Mobster tested it); every other kind always (Connect says why when its service's app isn't ready)."""
+        if kind.id != "slack":
+            return True
+        connectors = self.connectors()
+        if connectors is None:
+            return False
+        if any(row.get("preset") == "slack" and row.get("auth") == "oauth" for row in connectors.list()):
+            return True
+        return preset_list.offered(preset_list.preset("slack"), connectors.apps)
+
+    def begin(self, kind):
+        """Start connecting a destination of ``kind``: {"connect", "authorizeUrl"?}."""
+        if kind.id == "slack":
+            item, url = self._slack(kind)
+            return {"connect": item.public(), **({"authorizeUrl": url} if url else {})}
+        if kind.provider is None:
+            raise ValueError(f"A {kind.label.lower()} destination doesn't connect: give its fields instead")
+        app = self.apps.get(kind.provider)
+        if isinstance(app, shared.Unavailable):
+            raise APIError(f"{shared.why(kind.label, app.reason)}. Try again later.", 503, "connect_unavailable")
+        item = self._add(Connect(kind, self.clock()))
+        flow = self.sign_in_class(None, lambda ended, tokens, message: self._signed_in(item, tokens, message),
+                                  name=kind.label, app=app, keep=kind.keep)
+        try:
+            url = flow.begin()
+        except oauth.OAuthError as error:
+            self._pop(item.id)
+            raise APIError(error.message, 502, "sign_in_failed") from None
+        item.flow = flow
+        return {"connect": item.public(), "authorizeUrl": url}
+
+    def _signed_in(self, item, tokens, message):
+        """On the sign-in's thread when the browser came back: what the account offers, then done."""
+        if tokens is None:
+            item.state, item.message = "failed", message
+            return
+        try:
+            found = item.kind.connected(self.call, tokens)
+        except ValueError as error:
+            item.state, item.message = "failed", str(error)
+            return
+        except net.NetError as error:
+            item.state, item.message = "failed", f"{error.message} Connect again."
+            return
+        except Exception:  # noqa: BLE001 -- a connect that broke says so; the app stays up
+            log.exception("outlets: a connect failed unexpectedly")
+            item.state, item.message = "failed", f"Mobster couldn't finish connecting {item.kind.label}. Connect again."
+            return
+        item.found, item.at, item.state = found, self.clock(), "done"
+
+    def _slack(self, kind):
+        """(connect, authorizeUrl | None): done at once with a signed-in Slack connector; else the Slack connector,
+        added when there is none, signs in now, and the connect waits for it (``get``)."""
+        connectors = self.connectors()
+        if connectors is None:
+            raise APIError(SLACK_OFF, 503, "connectors_off")
+        rows = [row for row in connectors.list() if row.get("preset") == "slack"]
+        item = Connect(kind, self.clock())
+        signed = next((row for row in rows if row.get("auth") == "oauth"), None)
+        if signed is not None:
+            self._slack_found(item, connectors, signed["id"], refuse=True)
+            return self._add(item), None
+        row = rows[0] if rows else None
+        if row is None:
+            app = connectors.apps.get("slack")
+            if isinstance(app, shared.Unavailable):
+                raise APIError(f"{shared.why('Slack', app.reason)}. Connect Slack with your own app under Use in "
+                               "tasks, then add the destination.", 409, "slack_own_app")
+            row = connectors.add({"preset": "slack"})
+        try:
+            url = connectors.begin_sign_in(row["id"])["authorizeUrl"]
+        except ValueError as error:
+            # No app to sign in with: Mobster's isn't ready and you have none of your own (connectors/service.py).
+            raise APIError(str(error).rstrip(".") + ".", 409, "slack_own_app") from None
+        item.connector = row["id"]
+        return self._add(item), url
+
+    def _slack_found(self, item, connectors, connector_id, refuse=False):
+        """Done with the channels the Slack connector's sign-in sees."""
+        from ..connectors import client as mcp
+        try:
+            token = connectors.bearer(connector_id)
+            item.found = item.kind.connected(self.call, {"access_token": token, "connector": connector_id})
+            item.state, item.at = "done", self.clock()
+        except (mcp.AuthNeeded, APIError):
+            message = "Slack needs you to sign in again under Use in tasks. Then add the destination."
+            if refuse:
+                raise APIError(message, 409, "slack_own_app") from None
+            item.state, item.message = "failed", message
+        except (mcp.NotSent, net.NetError, ValueError) as error:
+            message = getattr(error, "message", None) or str(error)
+            if refuse:
+                raise APIError(message, 502, "slack_unreachable") from None
+            item.state, item.message = "failed", message
+
+    def _follow(self, item):
+        """A Slack connect waiting for the connector's sign-in: done or failed once that is."""
+        connectors = self.connectors()
+        row = next((row for row in (connectors.list() if connectors is not None else ())
+                    if row["id"] == item.connector), None)
+        sign_in = (row or {}).get("signIn") or {}
+        if row is None:
+            item.state, item.message = "failed", "Slack was removed from Use in tasks. Connect again."
+        elif sign_in.get("state") == "failed":
+            item.state, item.message = "failed", sign_in.get("message") or "Slack didn't connect. Connect again."
+        elif row.get("auth") == "oauth" and sign_in.get("state") != "waiting":
+            self._slack_found(item, connectors, row["id"])
+
+    def get(self, connect_id):
+        item = self._items.get(connect_id) if isinstance(connect_id, str) else None
+        if item is None:
+            raise APIError(GONE, 404, "not_found")
+        if item.connector is not None and item.state == "waiting":
+            self._follow(item)
+        return item.public()
+
+    def found(self, connect_id, kind_id):
+        """What a finished connect of ``kind_id`` found, for saving a destination with it. ValueError otherwise."""
+        self._sweep()
+        item = self._items.get(connect_id) if isinstance(connect_id, str) else None
+        if item is None or item.kind.id != kind_id:
+            raise ValueError(GONE)
+        if item.state != "done":
+            raise ValueError(item.message or f"Finish connecting {item.kind.label} in your browser first.")
+        return item.found
+
+    def cancel(self, connect_id):
+        item = self._pop(connect_id)
+        if item is None:
+            raise APIError(GONE, 404, "not_found")
+        return connect_id
+
+    def drop(self, connect_id):
+        """Forget a connect whose tokens are saved now."""
+        self._pop(connect_id)
+
+    def close(self):
+        with self._lock:
+            items, self._items = list(self._items.values()), {}
+        for item in items:
+            if item.flow is not None:
+                item.flow.cancel()
+
+    def _add(self, item):
+        self._sweep()
+        with self._lock:
+            while len(self._items) >= MAX_CONNECTS:
+                oldest = min(self._items.values(), key=lambda value: value.at)
+                self._items.pop(oldest.id)
+                if oldest.flow is not None:
+                    oldest.flow.cancel()
+            self._items[item.id] = item
+        return item
+
+    def _pop(self, connect_id):
+        with self._lock:
+            item = self._items.pop(connect_id, None) if isinstance(connect_id, str) else None
+        if item is not None and item.flow is not None:
+            item.flow.cancel()
+        return item
+
+    def _sweep(self):
+        """Forget what finished KEEP_SECONDS ago, and a sign-in nobody came back to (its own wait ended it)."""
+        now = self.clock()
+        with self._lock:
+            stale = [key for key, item in self._items.items()
+                     if now - item.at > (KEEP_SECONDS if item.state != "waiting" else oauth.WAIT_SECONDS + 60)]
+        for key in stale:
+            self._pop(key)
+
+
+class NoToken(Exception):
+    """No access token now; ``outcome`` says why. Nothing was sent."""
+
+    def __init__(self, outcome):
+        super().__init__(outcome.message)
+        self.outcome = outcome
+
+
+def access(ctx, label, refresh=False):
+    """The access token a connected destination sends, renewed through the license API first when it's expiring or
+    ``refresh`` (after a 401), and saved (``ctx.keep``)."""
+    saved = ctx.saved
+    # A Notion destination saved before 15 Oct 2026 holds an internal integration's token, which never expires.
+    tokens = saved.get("oauth") or ({"access_token": saved["token"]} if saved.get("token") else None)
+    if not tokens or not tokens.get("access_token"):
+        raise NoToken(Outcome(False, False, None, f"Mobster has no {label} sign-in for this. " + again(label),
+                              unsent=True))
+    if not (refresh or oauth.expiring(tokens, ctx.wall)):
+        return tokens["access_token"]
+    if not tokens.get("refresh_token"):
+        raise NoToken(Outcome(False, False, None, f"{label} signed Mobster out. " + again(label), unsent=True))
+    try:
+        tokens = ctx.refresh(tokens)
+    except oauth.OAuthError as error:
+        if error.retry:
+            raise NoToken(Outcome(False, True, None, f"Mobster couldn't renew its {label} sign-in. {error.message}",
+                                  unsent=True)) from None
+        raise NoToken(Outcome(False, False, None, f"{label} signed Mobster out. " + again(label), unsent=True)) \
+            from None
+    ctx.keep(tokens)
+    return tokens["access_token"]

mobile_agent/outlets/folder.py

@@ -0,0 +1,180 @@
+"""A folder destination: each result is appended to one file in a folder you chose, as a CSV row or a JSON line."""
+
+import csv
+import errno
+import fcntl
+import io
+import json
+import os
+import re
+import stat
+from pathlib import Path
+
+from .kinds import Kind, cell, flat
+from .webhook import Outcome
+
+FILE_NAME = re.compile(r"[^/\\:\x00-\x1f]{1,96}\.(csv|jsonl)", re.IGNORECASE)
+DEFAULT_FILE = "Mobster results.csv"
+HEADER_BYTES = 65_536
+
+
+def home():
+    """The home folder (tests replace it)."""
+    return Path.home()
+
+
+def shown(path):
+    """``path`` with the home folder written as ~."""
+    try:
+        return "~/" + str(Path(path).relative_to(home().resolve())) if Path(path) != home().resolve() else "~"
+    except ValueError:
+        return str(path)
+
+
+def inside_home(value):
+    """The folder ``value`` names (~ allowed), resolved, when it exists inside the home folder; ValueError else."""
+    text = value.strip() if isinstance(value, str) else ""
+    if not text:
+        raise ValueError("Choose a folder.")
+    if len(text) > 1024 or "\x00" in text:
+        raise ValueError("That isn't a folder's path.")
+    base = home().resolve()
+    path = Path(text.replace("~", str(base), 1) if text.startswith("~") else text)
+    if not path.is_absolute():
+        raise ValueError("Choose a folder in your home folder, such as ~/Documents.")
+    try:
+        real = path.resolve(strict=True)
+    except (OSError, RuntimeError):
+        raise ValueError("That folder doesn't exist. Choose one that does.") from None
+    if real != base and base not in real.parents:
+        raise ValueError("Choose a folder in your home folder. Mobster doesn't write anywhere else.")
+    if not real.is_dir():
+        raise ValueError("That's a file, not a folder.")
+    return real
+
+
+def file_name(value):
+    text = " ".join(value.split()) if isinstance(value, str) else ""
+    if not text:
+        return DEFAULT_FILE
+    if text.startswith(".") or not FILE_NAME.fullmatch(text):
+        raise ValueError("Name the file like Results.csv or Results.jsonl.")
+    return text
+
+
+class Folder(Kind):
+    id, label = "folder", "Folder"
+    example = "Results file"
+    fields = ("folder", "file")
+    replay_safe = False
+    keychain = False
+
+    def setup(self, body, current=None):
+        config = dict(current["row"]["config"]) if current else {}
+        if current is None or "folder" in body:
+            config["folder"] = shown(inside_home(body.get("folder")))
+        if current is None or "file" in body:
+            config["file"] = file_name(body.get("file"))
+        config["format"] = "jsonl" if config["file"].lower().endswith(".jsonl") else "csv"
+        if current is not None and not ({"folder", "file"} & set(body)):
+            return {}
+        target = config["folder"].rstrip("/") + "/" + config["file"]
+        if (inside_home(config["folder"]) / config["file"]).is_symlink():
+            raise ValueError("That file is a link. Name another file.")
+        return {"hint": target, "config": config, "last_test": None}
+
+    @staticmethod
+    def _open(config):
+        """The file, opened to append (created 0644 when new): (fd, path). OSError or ValueError when it can't be."""
+        folder = inside_home(config["folder"])
+        path = folder / config["file"]
+        # Only ever appends: never truncates, renames or replaces the file, and refuses a link or a non-regular file.
+        fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o644)
+        try:
+            if not stat.S_ISREG(os.fstat(fd).st_mode):
+                raise ValueError("That isn't a regular file.")
+        except BaseException:
+            os.close(fd)
+            raise
+        return fd, path
+
+    @staticmethod
+    def _header(path):
+        """The file's first line as CSV column names, and whether it ends with a line break; ([], True) when empty."""
+        fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_CLOEXEC)
+        with os.fdopen(fd, "rb") as handle:
+            head = handle.read(HEADER_BYTES)
+            size = os.fstat(handle.fileno()).st_size
+            ends = True
+            if size:
+                handle.seek(size - 1)
+                ends = handle.read(1) in (b"\n", b"\r")
+        if not head:
+            return [], True
+        first = head.decode("utf-8-sig", errors="replace").splitlines()[0] if head.strip() else ""
+        names = next(csv.reader(io.StringIO(first)), []) if first else []
+        return [name.strip() for name in names], ends
+
+    def lines(self, config, body, path):
+        """The bytes to append for ``body``."""
+        if config.get("format") == "jsonl":
+            document = {key: value for key, value in body.items() if key != "screenshot"}
+            return (json.dumps(document, ensure_ascii=False, separators=(",", ":")) + "\n").encode("utf-8")
+        row = flat(body)
+        header, ends = self._header(path)
+        out = io.StringIO()
+        writer = csv.writer(out, lineterminator="\n")
+        if not ends:
+            out.write("\n")
+        if not header:
+            header = list(row)
+            writer.writerow(header)
+        lower = {name.casefold(): value for name, value in row.items()}
+        writer.writerow([cell(lower.get(name.casefold(), "")) for name in header])
+        return out.getvalue().encode("utf-8")
+
+    def _append(self, ctx, body):
+        config = ctx.destination["config"]
+        where = config.get("folder", "the folder")
+        try:
+            fd, path = self._open(config)
+        except ValueError as error:
+            return Outcome(False, False, None, f"{error} Choose another in Settings › Connectors.")
+        except OSError as error:
+            if error.errno in (errno.ELOOP, errno.EMLINK):
+                return Outcome(False, False, None, f"{config.get('file')} is a link, so Mobster won't write to it. "
+                                                   "Name another file in Settings › Connectors.")
+            if error.errno in (errno.EACCES, errno.EPERM, errno.EROFS):
+                return Outcome(False, False, None, f"macOS didn't let Mobster write in {where}. Allow it in System "
+                                                   "Settings › Privacy & Security › Files and Folders, then resend.")
+            return Outcome(False, False, None, f"Mobster couldn't open {config.get('file')} in {where}.")
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+            data = self.lines(config, body, path)
+            written = os.write(fd, data)
+            if written != len(data):
+                return Outcome(False, False, None, f"Only part of the result fit in {config.get('file')}. Check the "
+                                                   "file and your disk's free space.")
+        except OSError as error:
+            if error.errno == errno.ENOSPC:
+                return Outcome(False, False, None, "The disk is full. Free some space, then resend.")
+            return Outcome(False, False, None, f"Mobster couldn't write to {config.get('file')}.")
+        finally:
+            os.close(fd)
+        return Outcome(True, False, None)
+
+    def send(self, ctx, body):
+        return self._append(ctx, body)
+
+    def test(self, ctx):
+        """Checks the folder and the file can be written, without adding a row."""
+        config = ctx.destination["config"]
+        try:
+            fd, _path = self._open(config)
+        except ValueError as error:
+            return Outcome(False, False, None, f"{error} Choose another in Settings › Connectors.")
+        except OSError:
+            return Outcome(False, False, None, f"Mobster can't write to {config.get('file')} in "
+                                               f"{config.get('folder')}. Choose another folder or file.")
+        os.close(fd)
+        return Outcome(True, False, None, f"Mobster can write to {config.get('file')}.")