py-ib-controller 0.0.0__py3-none-any.whl

ibcontroller/main.py

@@ -0,0 +1,156 @@
+"""ibcontroller's single-instance runner -- everything `cli.py`'s `run`/`init` commands
+need beyond argument parsing, which is deliberately kept there (this module has no
+`typer` dependency, so it stays directly testable/runnable without going through a CLI
+invocation -- `python -m ibcontroller.main` still works).
+
+**Config-dir scaffolding (`ensure_config_scaffold`)** Three bundled
+templates ship under `ibcontroller/data/` (`ibcontroller.toml.example`,
+`ibkr_settings.toml.example`, `labels.json.example`) and get copied into `config_dir`
+the first time each is missing -- but only `ibcontroller.toml` is copied under its
+*real* filename. The other two keep their `.example` suffix: `Config.settings_file`
+defaults to `None` (inert until a user points `[settings] file` at a renamed copy) and,
+more importantly, `labels.load_labels(config_dir=...)` applies `{config_dir}/
+labels.json` *unconditionally* the moment that exact filename exists -- auto-creating
+it live would be exactly the silent behavior-change . A user must deliberately rename it
+to opt in.
+
+`ibcontroller.toml.example` itself ships with every key commented out, so copying it
+as `ibcontroller.toml` changes nothing versus built-in defaults -- `run_async` still
+calls the real `load_config`, which still raises a clear `ConfigError` for the fields
+that have no default (`trading_mode`/`tws_version`/credentials), guiding a first run
+rather than silently starting with meaningless values.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import signal
+from collections.abc import Mapping
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from ibcontroller.app_dirs import resolve_app_dirs
+from ibcontroller.config import load_config
+from ibcontroller.control_loop import ShutdownCause, run_control_loop
+from ibcontroller.labels import load_labels
+
+logger = logging.getLogger("ibcontroller.main")
+
+# dest filename in config_dir -> bundled resource name under ibcontroller/data/. Only
+# "ibcontroller.toml" is copied under its real, load-bearing name -- see module
+# docstring for why the other two deliberately keep their ".example" suffix.
+_SCAFFOLD_FILES: dict[str, str] = {
+    "ibcontroller.toml": "ibcontroller.toml.example",
+    "ibkr_settings.toml.example": "ibkr_settings.toml.example",
+    "labels.json.example": "labels.json.example",
+}
+
+
+def _load_jar_path() -> Path:
+    """Resolves the bundled Java agent jar's real path, failing loudly (not
+    later, opaquely, inside `launch_instance`) if it isn't actually there --
+    e.g. a source checkout where `make` was never run, or a wheel built without
+    the jar present at build time (see the Makefile's `dist` target)."""
+
+    resource = resources.files("ibcontroller").joinpath("ibcontroller-agent.jar")
+    jar_path = Path(str(resource))
+    if not jar_path.is_file():
+        raise RuntimeError(
+            f"ibcontroller-agent.jar not found at {jar_path} -- build it first "
+            "(`make` from the project root) before running from a source checkout, "
+            "or reinstall the package if this is a wheel install."
+        )
+    return jar_path
+
+
+def ensure_config_scaffold(
+    config_dir: Path, log_dir: Path, *, force: bool = False
+) -> list[Path]:
+    """Creates `config_dir`/`log_dir` if missing, then copies each of
+    `_SCAFFOLD_FILES`'s bundled templates into `config_dir`, one file at a time, only
+    when the destination doesn't already exist (or unconditionally when `force=True`,
+    e.g. after an ibcontroller upgrade that changed the bundled examples). Returns the
+    list of files actually written, so a caller (`cli.py`'s `init`/`run`) can report
+    exactly what happened rather than silently overwriting or silently doing nothing."""
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    written: list[Path] = []
+    for dest_name, resource_name in _SCAFFOLD_FILES.items():
+        dest = config_dir / dest_name
+        if dest.exists() and not force:
+            continue
+        template = resources.files("ibcontroller").joinpath("data", resource_name)
+        dest.write_text(template.read_text(encoding="utf-8"), encoding="utf-8")
+        written.append(dest)
+    return written
+
+
+async def run_async(
+    config_dir: Path,
+    log_dir: Path,
+    *,
+    dotenv_path: Path | None = None,
+    cli_overrides: Mapping[str, Any] | None = None,
+) -> ShutdownCause:
+    """Loads config/labels for the one instance described by `{config_dir}/
+    ibcontroller.toml`, then runs it to completion via `control_loop.run_control_loop`.
+
+    Scaffolds `config_dir` first (non-forced -- see `ensure_config_scaffold`), so a
+    fresh install's first `run` produces the same starter files `init` would, then
+    fails with a clear `ConfigError` (not a `FileNotFoundError`) if the required fields
+    are still unset.
+
+    `labels=load_labels(config_dir=config_dir)` is the actual fix for Open item 11 --
+    today's `control_loop.run_control_loop`'s own default (`load_labels()`, no
+    `config_dir`) never sees a user's `{config_dir}/labels.json` override at all.
+
+    `cli_overrides`, if given, is passed straight through to `load_config` -- the
+    per-invocation `Config` field overrides `cli.py`'s `run` command builds from its
+    own `--trading-mode`/`--tws-path`/`--tws-settings-path`/`--instance` options.
+
+    Ctrl-C (`SIGINT`) and `SIGTERM` both cancel the running task -- the graceful-stop
+    contract `control_loop.py`'s own docstring already documents ("cancel this
+    coroutine's own task to request a graceful stop... a plain Ctrl-C in a CLI"),
+    wired up here for the first time. POSIX only (`loop.add_signal_handler`), matching
+    this project's current platform scope."""
+
+    ensure_config_scaffold(config_dir, log_dir)
+    config = load_config(
+        config_dir=config_dir,
+        log_dir=log_dir,
+        dotenv_path=dotenv_path,
+        cli_overrides=cli_overrides,
+    )
+    labels = load_labels(config_dir=config_dir)
+    agent_jar_path = _load_jar_path()
+
+    loop = asyncio.get_running_loop()
+    task = asyncio.ensure_future(
+        run_control_loop(config, agent_jar_path, labels=labels)
+    )
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, task.cancel)
+    try:
+        return await task
+    finally:
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            with contextlib.suppress(NotImplementedError, ValueError):
+                loop.remove_signal_handler(sig)
+
+
+def main() -> None:
+    """Thin synchronous wrapper for direct invocation (`python -m ibcontroller.main`).
+    `cli.py` (the package's real installed entry point, `ibcontroller` on `PATH`) calls
+    `run_async` directly instead, so it can catch `ConfigError` and report it as a clean
+    CLI error rather than a traceback."""
+    config_dir, log_dir = resolve_app_dirs()
+    asyncio.run(run_async(config_dir, log_dir))
+
+
+if __name__ == "__main__":
+    main()

ibcontroller/recognisers.py

@@ -0,0 +1,448 @@
+"""Matches windows that show up unprompted -- a stray pop-up, an
+existing-session conflict, a login-failure dialog, a warning dialog -- as
+opposed to windows an active sequence (Login, Settings) already expects and
+waits for directly via `actions.wait_for_event`.
+
+`RecognizerRegistry` holds an ordered list of `Recognizer`s, checked in
+order against each unprompted window; the first one whose `recognises()`
+returns `True` has its `handle()` awaited. `DeclarativeDismissRecognizer` is
+built from `labels.DismissRule` entries (`control_loop._build_registry`) for
+the common "match text/title, click one button" case; the remaining classes
+below handle cases with real conditional logic that isn't expressible as
+data. Every recogniser acts through `actions.py`'s primitives, the same as
+any other caller.
+
+`watch_for_unprompted_windows` runs for the agent's whole lifetime as a
+background task, watching `dispatcher.window_events` for `window_opened`
+events and routing each one through `handle_window_opened`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from collections.abc import Callable, Sequence
+from typing import Protocol
+
+import eventkit
+
+from ibcontroller.actions import click, dump
+from ibcontroller.agent_client import (
+    Component,
+    WindowEvent,
+    WindowGoneError,
+)
+from ibcontroller.config import AcceptIncomingConnections, ExistingSessionAction
+from ibcontroller.dispatch import Dispatcher
+from ibcontroller.labels import (
+    AcceptIncomingConnectionLabels,
+    DismissRule,
+    ExistingSessionLabels,
+    LoginFailedLabels,
+    TooManyFailedLoginAttemptsLabels,
+)
+
+logger = logging.getLogger(__name__)
+
+_WAIT_PATTERN = re.compile(
+    r"Please wait (?:(\d+) minutes? )?(?:& )?(?:(\d+) seconds?)?"
+)
+
+
+def _parse_wait_seconds(message: str) -> float:
+    """Parses a wait duration out of a "too many failed login attempts"
+    message (e.g. "Please wait 4 minutes & 47 seconds"), plus a 3 second
+    buffer. Returns just the buffer if `message` doesn't match."""
+    match = _WAIT_PATTERN.search(message)
+    minutes = int(match.group(1)) if match and match.group(1) else 0
+    seconds = int(match.group(2)) if match and match.group(2) else 0
+    return float(minutes * 60 + seconds + 3)
+
+
+class LoginFailedError(Exception):
+    """Raised by `LoginFailedRecognizer.handle` after dismissing a real
+    "Login failed" dialog -- signals that a cold restart is needed. Not
+    raised for a bug in this recogniser, which propagates as whatever
+    exception it actually is."""
+
+
+class Recognizer(Protocol):
+    def recognises(self, event: WindowEvent, components: list[Component]) -> bool:
+        """Returns whether this recogniser matches `event`. `components` is
+        the result of dumping the window (never `None` -- if the window
+        closed before the dump could complete, this recogniser is never
+        called)."""
+        ...
+
+    async def handle(
+        self,
+        event: WindowEvent,
+        components: list[Component],
+        dispatcher: Dispatcher,
+    ) -> None:
+        """Acts on a matched window -- dismissing it, clicking a button, or
+        otherwise responding to it."""
+        ...
+
+
+def is_credential_entry(components: list[Component]) -> bool:
+    """Returns whether `components` includes a live, visible credential
+    field. Checked before any recogniser runs -- credential fields are never
+    handled by this registry, only by Login's own field-fill."""
+    return any(c.credential_field and c.showing for c in components)
+
+
+class DeclarativeDismissRecognizer:
+    """One `Recognizer` per `labels.DismissRule`: matches `rule.match_title`
+    against the window's title and/or `rule.match_text` against any
+    component's `accessible_name`/`text`, then clicks `rule.click`. If both
+    `match_title` and `match_text` are given, both must match. `rule` is
+    public so a caller inspecting `RecognizerRegistry.handled` can identify
+    which rule fired, by name."""
+
+    def __init__(self, rule: DismissRule) -> None:
+        self.rule = rule
+
+    def recognises(self, event: WindowEvent, components: list[Component]) -> bool:
+        rule = self.rule
+        if rule.match_title is not None and rule.match_title not in (
+            event.window.title or ""
+        ):
+            return False
+        if rule.match_text is not None and not any(
+            (c.accessible_name is not None and rule.match_text in c.accessible_name)
+            or (c.text is not None and rule.match_text in c.text)
+            for c in components
+        ):
+            return False
+        return True
+
+    async def handle(
+        self,
+        event: WindowEvent,
+        components: list[Component],
+        dispatcher: Dispatcher,
+    ) -> None:
+        """Clicks `rule.click`, scoped to `event.window.window_id`."""
+        await click(dispatcher, self.rule.click, window_id=event.window.window_id)
+        logger.info("dismissed %s (declarative rule)", self.rule.name)
+
+
+class TooManyFailedLoginAttemptsRecognizer:
+    """Matches the server-side "too many failed login attempts" dialog by
+    message text (`text` primarily, `accessible_name` as a fallback).
+    Distinct from the 2FA-timeout retry `login.py`'s `LoginManager` handles
+    internally (that one is driven by elapsed time, not by recognising a
+    window).
+
+    When `relogin_enabled` is `True`, dismisses the dialog and calls
+    `schedule_retry` with the wait time (in seconds) parsed from the
+    message. When `False`, the dialog is left untouched for manual
+    handling. `schedule_retry` is a plain, synchronous callable -- it's
+    expected to schedule the actual retry as a background task, since
+    `handle()` returns immediately without waiting out the cooldown."""
+
+    def __init__(
+        self,
+        labels: TooManyFailedLoginAttemptsLabels,
+        relogin_enabled: bool,
+        schedule_retry: Callable[[float], None],
+    ) -> None:
+        self._labels = labels
+        self._relogin_enabled = relogin_enabled
+        self._schedule_retry = schedule_retry
+
+    def _matched_text(self, components: list[Component]) -> str | None:
+        prefix = self._labels.message_prefix
+        for c in components:
+            if c.text is not None and prefix in c.text:
+                return c.text
+            if c.accessible_name is not None and prefix in c.accessible_name:
+                return c.accessible_name
+        return None
+
+    def recognises(self, event: WindowEvent, components: list[Component]) -> bool:
+        return self._matched_text(components) is not None
+
+    async def handle(
+        self,
+        event: WindowEvent,
+        components: list[Component],
+        dispatcher: Dispatcher,
+    ) -> None:
+        if not self._relogin_enabled:
+            logger.warning(
+                "too many failed login attempts -- relogin disabled, "
+                "dialog left for manual handling"
+            )
+            return
+        message = self._matched_text(components) or ""
+        wait_seconds = _parse_wait_seconds(message)
+        logger.warning(
+            "too many failed login attempts -- retrying in %.0fs", wait_seconds
+        )
+        await click(
+            dispatcher,
+            self._labels.dismiss_button,
+            window_id=event.window.window_id,
+        )
+        self._schedule_retry(wait_seconds)
+
+
+class LoginFailedRecognizer:
+    """Matches a "Login failed" dialog by window title. Dismisses it and
+    raises `LoginFailedError` -- the restart itself isn't this recogniser's
+    job, only signalling that one is needed."""
+
+    def __init__(self, labels: LoginFailedLabels) -> None:
+        self._labels = labels
+
+    def recognises(self, event: WindowEvent, components: list[Component]) -> bool:
+        return self._labels.title in (event.window.title or "")
+
+    async def handle(
+        self,
+        event: WindowEvent,
+        components: list[Component],
+        dispatcher: Dispatcher,
+    ) -> None:
+        await click(
+            dispatcher,
+            self._labels.dismiss_button,
+            window_id=event.window.window_id,
+        )
+        logger.warning("IBController > login failed -- cold restart required")
+        raise LoginFailedError("login failed; cold restart required")
+
+
+class ExistingSessionRecognizer:
+    """Matches an existing-session-conflict dialog by window title. `action`
+    (`ExistingSessionAction`: manual/secondary/primary/primaryoverride)
+    selects how to resolve it; `is_logged_in` reports whether this session
+    has already reached `LOGGED_IN`, since the correct response differs
+    before vs. after login completes. Stateful: tracks whether a previous
+    attempt was already made this process, one instance per running agent."""
+
+    def __init__(
+        self,
+        labels: ExistingSessionLabels,
+        action: ExistingSessionAction,
+        is_logged_in: Callable[[], bool],
+    ) -> None:
+        self._labels = labels
+        self._action = action
+        self._is_logged_in = is_logged_in
+        self._attempted = False
+
+    def recognises(self, event: WindowEvent, components: list[Component]) -> bool:
+        return self._labels.title in (event.window.title or "")
+
+    async def handle(
+        self,
+        event: WindowEvent,
+        components: list[Component],
+        dispatcher: Dispatcher,
+    ) -> None:
+        if self._action is ExistingSessionAction.MANUAL:
+            logger.info(
+                "IBController > existing session detected -- manual, leaving for"
+                " the user"
+            )
+            return  # scenario 1: user must choose -- nothing to do
+        if self._action is ExistingSessionAction.SECONDARY:
+            # scenario 2: end this session, let the other one proceed
+            logger.info(
+                "IBController > existing session detected -- secondary, ending"
+                " this session"
+            )
+            await click(
+                dispatcher,
+                self._labels.cancel_buttons,
+                window_id=event.window.window_id,
+            )
+            return
+        if not self._is_logged_in():
+            # we are session B (login not yet complete)
+            if not self._attempted:
+                self._attempted = True
+                # scenario 3: don't know session A's type, continue this one
+                logger.info(
+                    "IBController > existing session detected -- first attempt, "
+                    "continuing this session"
+                )
+                await click(
+                    dispatcher,
+                    self._labels.continue_buttons,
+                    window_id=event.window.window_id,
+                )
+            else:
+                # scenario 4: session A must be primary/primaryoverride, end this one
+                logger.info(
+                    "IBController > existing session detected -- second attempt, ending"
+                    " this session"
+                )
+                await click(
+                    dispatcher,
+                    self._labels.cancel_buttons,
+                    window_id=event.window.window_id,
+                )
+        elif self._action is ExistingSessionAction.PRIMARY:
+            # scenario 5: we are session A, primary -- continue this, let the other exit
+            logger.info(
+                "IBController > existing session detected -- primary, continuing this"
+                " session"
+            )
+            await click(
+                dispatcher,
+                self._labels.continue_buttons,
+                window_id=event.window.window_id,
+            )
+        else:
+            # scenario 6: we are session A, primaryoverride -- let the other proceed
+            logger.info(
+                "IBController > existing session detected -- primaryoverride, ending"
+                " this session"
+            )
+            await click(
+                dispatcher,
+                self._labels.cancel_buttons,
+                window_id=event.window.window_id,
+            )
+
+
+class AcceptIncomingConnectionsRecognizer:
+    """Matches the "Accept incoming connection" dialog TWS/Gateway shows when
+    a client connects on the API socket, by window title (ported from IBC's
+    own `AcceptIncomingConnectionDialogHandler`; title matching, not IBC's
+    body-label search, to match this project's own convention for every
+    other simple dialog here -- confirmed as a valid alternative by ibctl's
+    own independent, live-tested handler, which matches on title too).
+    `action` (`AcceptIncomingConnections`: manual/accept/reject) selects the
+    response; `MANUAL` leaves the dialog for the user, matching IBC's own
+    handler."""
+
+    def __init__(
+        self,
+        labels: AcceptIncomingConnectionLabels,
+        action: AcceptIncomingConnections,
+    ) -> None:
+        self._labels = labels
+        self._action = action
+
+    def recognises(self, event: WindowEvent, components: list[Component]) -> bool:
+        return self._labels.title in (event.window.title or "")
+
+    async def handle(
+        self,
+        event: WindowEvent,
+        components: list[Component],
+        dispatcher: Dispatcher,
+    ) -> None:
+        if self._action is AcceptIncomingConnections.MANUAL:
+            logger.info(
+                "IBController > incoming API connection -- manual, leaving for the user"
+            )
+            return
+        if self._action is AcceptIncomingConnections.ACCEPT:
+            await click(
+                dispatcher,
+                self._labels.accept_buttons,
+                window_id=event.window.window_id,
+            )
+            logger.info("IBController > incoming API connection -- accepted")
+        else:
+            await click(
+                dispatcher,
+                self._labels.reject_buttons,
+                window_id=event.window.window_id,
+            )
+            logger.info("IBController > incoming API connection -- rejected")
+
+
+class RecognizerRegistry:
+    """Ordered list of `Recognizer`s, checked in sequence; `dispatch()` runs
+    the first one that matches. A bug in a recogniser propagates unchanged,
+    not caught here -- there's no plugin/config-rule tier yet to isolate
+    failures from."""
+
+    def __init__(self, registry: Sequence[Recognizer]) -> None:
+        self._registry = list(registry)
+        self.handled: eventkit.Event = eventkit.Event()
+        """Emits `(recognizer, event)` -- two positional args -- right after
+        that recognizer's own `handle()` returns successfully. Lets a caller
+        know a specific rule has run (e.g. to know a blocking dialog is now
+        gone) before proceeding."""
+
+    def recognises(self, event: WindowEvent, components: list[Component]) -> bool:
+        """Read-only: whether any registered recogniser matches, without
+        running its `handle()`. Used by `diagnostics.watch_for_diagnostics`
+        to classify a window as "known"/"unknown" -- the same classification
+        `dispatch()` itself uses, exposed without the side effect."""
+        return any(r.recognises(event, components) for r in self._registry)
+
+    async def dispatch(
+        self,
+        event: WindowEvent,
+        components: list[Component],
+        dispatcher: Dispatcher,
+    ) -> bool:
+        """Runs the first matching recogniser's `handle()` against
+        `event`/`components`, emitting `handled`. Returns whether anything
+        matched."""
+        for recognizer in self._registry:
+            if recognizer.recognises(event, components):
+                await recognizer.handle(event, components, dispatcher)
+                self.handled.emit(recognizer, event)
+                return True
+        return False
+
+
+async def handle_window_opened(
+    registry: RecognizerRegistry,
+    event: WindowEvent,
+    dispatcher: Dispatcher,
+) -> bool:
+    """Dumps `event.window`'s components, then dispatches: refuses (returns
+    `False`) if the window shows a live credential field, otherwise routes it
+    through `registry.dispatch`. Returns `False` if the window closed before
+    it could be dumped (`WindowGoneError`) or if nothing matched."""
+    try:
+        components = await dump(
+            dispatcher, window=event.window.title, window_id=event.window.window_id
+        )
+    except WindowGoneError:
+        return False
+    if is_credential_entry(components):
+        return False
+    return await registry.dispatch(event, components, dispatcher)
+
+
+async def watch_for_unprompted_windows(
+    registry: RecognizerRegistry,
+    dispatcher: Dispatcher,
+) -> None:
+    """Runs for the agent's whole lifetime: watches `dispatcher.window_events`
+    for `window_opened` events and routes each one through
+    `handle_window_opened`, logging any that go unhandled. Meant to be
+    started via `asyncio.create_task`, not awaited directly -- it never
+    returns on its own."""
+    queue: asyncio.Queue[WindowEvent] = asyncio.Queue()
+
+    def on_event(event: WindowEvent) -> None:
+        if event.kind == "window_opened":
+            queue.put_nowait(event)
+
+    dispatcher.window_events.connect(on_event)
+    try:
+        while True:
+            event = await queue.get()
+            handled = await handle_window_opened(registry, event, dispatcher)
+            if not handled:
+                logger.info(
+                    "unhandled unprompted window: %s %r",
+                    event.window.class_,
+                    event.window.title,
+                )
+    finally:
+        dispatcher.window_events.disconnect(on_event)