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

ibcontroller/dispatch.py

@@ -0,0 +1,288 @@
+"""Serializes access to one running agent instance: events in, commands out,
+both serialized through one `Dispatcher`. Built on `agent_client.py`'s typed
+connections -- this module only ever handles `PingResult`/`Component`/
+`WindowEvent` and the rest of that module's vocabulary, never a raw line or
+dict itself.
+
+One `Dispatcher` per running agent instance (live and paper are separate
+objects, each with its own connections, queue, and event stream) -- nothing
+here is a module-level singleton.
+
+**Trace mode**: pass `instance` (the same name `logging_setup.configure_trace`
+was called with) to emit every command and every raw event message as NDJSON
+to `cmd-{instance}.jsonl`/`events-{instance}.jsonl`, via the
+`ibcontroller.trace.{instance}.{cmd,event}` loggers. This module only builds
+the JSON line and calls `logger.debug(line)` -- the files, handlers, and
+listener threads are owned by `logging_setup.py`, so nothing here ever
+blocks the event loop on a write.
+
+Event arrivals are also logged at DEBUG in the normal app log (one
+human-readable line per message, via `_describe_event`), independent of
+trace mode.
+
+Credentials never reach this file as plaintext: `Config.username`/`password`
+are `Secret`, not `str`; `agent_client.set_text` is the only place that ever
+unwraps one, so nothing downstream (including this module) ever sees the
+bare value. A `Secret` passed as a `set_text` argument serializes as
+`"Secret('<redacted>')"` via this file's existing `repr` fallback.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import Any, TypeVar
+
+import eventkit
+
+from ibcontroller.agent_client import (
+    AgentClientError,
+    AgentCommandConnection,
+    AgentEventConnection,
+    AgentEventMessage,
+    Hello,
+    Keepalive,
+    Overflow,
+    Snapshot,
+    WindowEvent,
+    converter,
+)
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+_CommandCall = Callable[[], Awaitable[T]]
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat(timespec="milliseconds")
+
+
+def _describe_call(call: _CommandCall[object]) -> dict[str, Any]:
+    """Best-effort trace-file description of `call`. Only a
+    `functools.partial` of a bound `AgentCommandConnection` method (the
+    documented convention for `send_command` calls) can actually be named
+    and have its arguments logged."""
+    if isinstance(call, functools.partial):
+        return {
+            "cmd": getattr(call.func, "__name__", repr(call.func)),
+            "args": list(call.args),
+        }
+    return {"cmd": getattr(call, "__name__", repr(call))}
+
+
+def _safe_unstructure(value: object) -> object:
+    """Unstructures `value` for the trace file, falling back to `repr` for
+    anything `cattrs` can't handle -- trace serialization must never be the
+    reason a real command fails."""
+    try:
+        return converter.unstructure(value)
+    except Exception:
+        return repr(value)
+
+
+def _describe_event(msg: AgentEventMessage) -> str:
+    """Returns one human-readable line describing `msg`, for the DEBUG app
+    log (`_event_reader`). The raw JSON of the same message still lives in
+    the trace file when tracing is enabled. Event content is window metadata
+    only (class/title/window_id/seq), never field values, so it's always
+    safe to log."""
+    if isinstance(msg, Hello):
+        return f"event: hello protocol_version={msg.protocol_version}"
+    if isinstance(msg, Snapshot):
+        return f"event: snapshot windows={len(msg.windows)}"
+    if isinstance(msg, WindowEvent):
+        win = msg.window
+        title = f" title={win.title!r}" if win.title else ""
+        wid = f" window_id={win.window_id}" if win.window_id else ""
+        return f"event: {msg.kind} class={win.class_}{title}{wid} seq={msg.seq}"
+    if isinstance(msg, Overflow):
+        return f"event: overflow from_seq={msg.from_seq}"
+    if isinstance(msg, Keepalive):
+        return f"event: keepalive ts={msg.ts}"
+    return f"event: {type(msg).__name__}"
+
+
+class Dispatcher:
+    """Owns one command socket connection and one event socket connection
+    for a single running agent instance.
+
+    `window_events` carries `WindowEvent` messages only -- `Hello`/`Snapshot`
+    are connection-lifecycle markers and `Keepalive` is a liveness signal,
+    none of the three are forwarded. `Overflow` is logged as a warning (real
+    event loss on the agent's own side), not silently dropped. All four
+    still reach the trace file when tracing is enabled (see the module
+    docstring) -- that stream mirrors raw traffic, unlike `window_events`.
+    """
+
+    def __init__(
+        self,
+        command_conn: AgentCommandConnection,
+        event_conn: AgentEventConnection,
+        *,
+        instance: str | None = None,
+    ) -> None:
+        """`command_conn`/`event_conn` are the two socket connections this
+        Dispatcher owns. `instance`, if given, enables trace mode under that
+        name (see the module docstring)."""
+        self._command_conn = command_conn
+        self._event_conn = event_conn
+        self._command_queue: asyncio.Queue[
+            tuple[_CommandCall[object], asyncio.Future[object], int]
+        ] = asyncio.Queue()
+        self.window_events: eventkit.Event = eventkit.Event()
+        self._tasks: list[asyncio.Task[None]] = []
+        self._trace_cmd_logger: logging.Logger | None = None
+        self._trace_event_logger: logging.Logger | None = None
+        # A single gate covering both streams: configure_trace sets both to
+        # the same level, so the .cmd logger's level is the reliable answer.
+        # Resolved once at construction -- configure_trace must have run
+        # (with this instance's name) before the Dispatcher is built.
+        self._trace_enabled = False
+        if instance is not None:
+            prefix = f"ibcontroller.trace.{instance}"
+            self._trace_cmd_logger = logging.getLogger(f"{prefix}.cmd")
+            self._trace_event_logger = logging.getLogger(f"{prefix}.event")
+            self._trace_enabled = self._trace_cmd_logger.isEnabledFor(logging.DEBUG)
+        self._trace_seq = 0
+
+    async def start(self) -> None:
+        """Connects both sockets and starts the event-reader/command-worker
+        coroutines as background tasks. Call once; not idempotent."""
+        await self._command_conn.connect()
+        await self._event_conn.connect()
+        self._tasks = [
+            asyncio.create_task(self._event_reader(), name="ibcontroller-event-reader"),
+            asyncio.create_task(
+                self._command_worker(), name="ibcontroller-command-worker"
+            ),
+        ]
+
+    @property
+    def command_conn(self) -> AgentCommandConnection:
+        """The `AgentCommandConnection` this Dispatcher owns -- lets
+        `actions.py`'s functions build `send_command` calls against it
+        without threading a second, always-the-same reference alongside
+        `dispatcher`."""
+        return self._command_conn
+
+    @property
+    def tasks(self) -> tuple[asyncio.Task[None], ...]:
+        """The background event-reader/command-worker tasks, for an external
+        supervisor to watch for either one ending unexpectedly (e.g. the
+        agent process died, or Gateway closed) -- a connection loss ends
+        `_event_reader`'s loop with no exception, nothing to catch here."""
+        return tuple(self._tasks)
+
+    async def stop(self) -> None:
+        """Cancels both background tasks and closes both connections. Any
+        command still queued or in flight is abandoned -- its
+        `send_command` caller sees a `CancelledError`, not a result. Trace
+        streams are `logging_setup.py`'s concern, not this layer's; the
+        caller drains those separately via `logging_setup.stop_logging()`."""
+        for task in self._tasks:
+            task.cancel()
+        for task in self._tasks:
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+        await self._command_conn.close()
+        await self._event_conn.close()
+
+    async def send_command(self, call: _CommandCall[T]) -> T:
+        """Queues `call` and waits for the single `_command_worker` to run
+        it, never overlapping another command on the same connection (the
+        wire protocol has no request IDs). `call` should be a
+        `functools.partial` of a bound `AgentCommandConnection` method, e.g.
+        `functools.partial(dispatcher.command_conn.set_text, "u", "x")` --
+        the trace file can only name the command and its arguments when it
+        can introspect `call.func`/`call.args`."""
+        loop = asyncio.get_running_loop()
+        done: asyncio.Future[T] = loop.create_future()
+        self._trace_seq += 1
+        seq = self._trace_seq
+        self._trace_cmd({"seq": seq, "direction": "sent", **_describe_call(call)})
+        # The queue is declared over `object` so one queue can carry every command's
+        # differently-typed result; a per-call `T` narrows correctly at the type
+        # checker's boundary here but not through the queue's own invariant generic.
+        await self._command_queue.put((call, done, seq))  # type: ignore[arg-type]
+        return await done
+
+    async def _event_reader(self) -> None:
+        """Reads events from `AgentEventConnection.messages()`, emits each
+        `WindowEvent` on `window_events`, and logs every message at DEBUG
+        and to the trace file. Deliberately doesn't catch anything -- a
+        malformed line (`ProtocolError`) means the connection is desynced,
+        not a transient hiccup; the task ending is the correct signal for
+        whatever supervises this instance to notice and act on."""
+        async for msg in self._event_conn.messages():
+            logger.debug("%s", _describe_event(msg))
+            self._trace_event(
+                {"class": type(msg).__name__, **_safe_unstructure(msg)}  # type: ignore[dict-item]
+            )
+            if isinstance(msg, WindowEvent):
+                self.window_events.emit(msg)
+            elif isinstance(msg, Overflow):
+                logger.warning(
+                    "agent event queue overflow, events lost from seq=%s",
+                    msg.from_seq,
+                )
+
+    async def _command_worker(self) -> None:
+        """Runs one queued command at a time, resolving its future with the
+        result or the raised exception. Catches broad `Exception`
+        deliberately -- one bad command must not kill this task, which
+        would silently stop every future command for this instance from
+        ever being processed."""
+        while True:
+            call, done, seq = await self._command_queue.get()
+            if done.cancelled():
+                continue
+            try:
+                result = await call()
+            except Exception as exc:
+                code = (
+                    exc.__class__.__name__
+                    if isinstance(exc, AgentClientError)
+                    else None
+                )
+                self._trace_cmd(
+                    {"seq": seq, "direction": "error", "error": code or repr(exc)}
+                )
+                if not done.cancelled():
+                    done.set_exception(exc)
+            else:
+                self._trace_cmd(
+                    {
+                        "seq": seq,
+                        "direction": "result",
+                        "result": _safe_unstructure(result),
+                    }
+                )
+                if not done.cancelled():
+                    done.set_result(result)
+
+    def _trace_cmd(self, payload: dict[str, Any]) -> None:
+        self._trace(self._trace_cmd_logger, payload)
+
+    def _trace_event(self, payload: dict[str, Any]) -> None:
+        self._trace(self._trace_event_logger, payload)
+
+    def _trace(
+        self, trace_logger: logging.Logger | None, payload: dict[str, Any]
+    ) -> None:
+        if not self._trace_enabled or trace_logger is None:
+            return
+        # "_ts" (not "ts"): a real message field can be named "ts" too
+        # (Keepalive's own payload has one) -- a flat merge with a matching
+        # key would silently overwrite this trace-line's own timestamp.
+        line = json.dumps({"_ts": _now_iso(), **payload}, default=repr)
+        # A DEBUG emit into the instance-scoped trace logger; the write itself
+        # happens on `logging_setup`'s listener thread, never on this event loop.
+        trace_logger.debug(line)

ibcontroller/labels.py

@@ -0,0 +1,242 @@
+"""Window/button labels the built-in recognisers (`recognisers.py`, L5) match
+against -- externalized to JSON rather than hardcoded. If IBKR renames a
+button in a future release, a user patches this file instead of waiting for a
+new ibcontroller release or forking Python code.
+
+A bundled default (`data/labels.json`, shipped with the package so
+ibcontroller works out of the box) is layered under an optional
+`labels.json` in `app_dirs.resolve_app_dirs()`'s `config_dir` -- merged one
+field at a time (`{"login": {"gateway_titles": [...]}}` overrides just that
+one field, leaving every other label and domain untouched), not a full
+replacement. `dismiss_rules` (below) is a list, not a nested object, so an
+override replaces the whole list, not one entry within it -- a user
+extending it copies the bundled entries into their own override file rather
+than appending.
+
+`dismiss_rules` is a real exception to "this file is just labels, not config
+rules": each entry is a full declarative `Recognizer` (see `DismissRule`'s
+own docstring), not just a name-to-text mapping the way every other group
+here is. It stays here to reuse this module's bundled-default-plus-override
+loader, rather than a second loader elsewhere. A *config rule* in the wider
+sense (arbitrary match -> arbitrary `ACTIONS` sequence, user-authored,
+per-deployment) is still a different, larger thing than a `DismissRule`
+(fixed shape: one match, one click)."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import attrs
+import cattrs
+
+converter = cattrs.Converter()
+
+
+@attrs.define(frozen=True)
+class LoginLabels:
+    gateway_titles: list[str]
+    tws_titles: list[str]
+    login_buttons: list[str]
+    api_type_ib_api: str
+    api_type_fix: str
+    trading_mode_live: str
+    trading_mode_paper: str
+    username_field: str
+    password_field: str
+    starting_application_title: str
+    """Gateway only. The splash/"Authenticating..." frame's *final* title, read
+    at `WINDOW_CLOSED` time, is the Gateway login-completion signal --
+    the main window opening is not a valid signal, since it renders fully
+    before authentication (including 2FA) actually finishes. See
+    `login.py`'s `_wait_for_outcome_gateway`."""
+    tws_main_window_menu_item: str
+    """TWS only. A `File > Lock Application` menu item existing on a
+    newly-opened top-level window is the TWS login-completion signal -- TWS's
+    real main window title is account-specific, so a title match can't be
+    used here the way it can for Gateway. See `login.py`'s
+    `_wait_for_outcome_tws`."""
+
+
+@attrs.define(frozen=True)
+class MfaLabels:
+    title: str
+
+
+@attrs.define(frozen=True)
+class ExistingSessionLabels:
+    title: str
+    continue_buttons: list[str]
+    cancel_buttons: list[str]
+
+
+@attrs.define(frozen=True)
+class AcceptIncomingConnectionLabels:
+    """`accept_buttons` tries "OK" then "Yes" in order; `reject_buttons` is
+    "No"."""
+
+    title: str
+    accept_buttons: list[str]
+    reject_buttons: list[str]
+
+
+@attrs.define(frozen=True)
+class LoginFailedLabels:
+    title: str
+    dismiss_button: str
+
+
+class LabelsError(Exception):
+    """A malformed entry in `labels.json` (bundled or override) -- e.g. a
+    `DismissRule` with neither `match_title` nor `match_text` set."""
+
+
+@attrs.define(frozen=True)
+class DismissRule:
+    """One declarative "just dismiss this" recogniser: a dialog that's always
+    recognised the same simple way (title-contains and/or text-contains) and
+    always dismissed the same simple way (click one button).
+
+    `recognisers.DeclarativeDismissRecognizer` implements the `Recognizer`
+    Protocol generically for every rule here.
+
+    At least one of `match_title`/`match_text` is required (checked in
+    `__attrs_post_init__`, so a malformed rule fails at `load_labels()` time,
+    not silently at first dispatch). If both are given, **both** must match
+    (AND, not OR), to avoid over-matching an unrelated dialog that happens to
+    share only one of the two conditions. `match_text` checks every
+    component's `text` *and* `accessible_name`, since which field a label's
+    text lands in depends on the real Swing component type -- `JLabel` text
+    only ever surfaces via `accessible_name`."""
+
+    name: str
+    click: str
+    match_title: str | None = None
+    match_text: str | None = None
+
+    def __attrs_post_init__(self) -> None:
+        if self.match_title is None and self.match_text is None:
+            raise LabelsError(
+                f"dismiss_rules entry {self.name!r} needs at least one of "
+                "'match_title'/'match_text'"
+            )
+
+
+@attrs.define(frozen=True)
+class TooManyFailedLoginAttemptsLabels:
+    """`message_prefix` matches the start of the dialog text ("Too many
+    failed login attempts. Please wait N minute(s) & M second(s) before
+    attempting to re-login again."), not the window title."""
+
+    message_prefix: str
+    dismiss_button: str
+
+
+@attrs.define(frozen=True)
+class SettingsLabels:
+    """Labels for the Global Configuration dialog (see `settings.py`).
+
+    `gateway_menu_path` is Gateway's `Configure/Settings`. TWS has no
+    `Configure` menu at all; `open_settings_dialog` uses `tws_menu_path`
+    (`File/Global Configuration...`, Mosaic layout) -- live-confirmed
+    2026-09-16 as the real path, after `tws_menu_path_classic`
+    (`Edit/Global Configuration...`) produced a clean `ElementNotFoundError`
+    every run (Mosaic has no `Edit/Global Configuration...` item; earlier
+    mistaken for #40's wrong-frame race). `tws_menu_path_classic` is defined
+    but unused -- a real Classic/Mosaic fallback matching IBC's own
+    `GetConfigDialogTask` order is tracked separately as #39.
+
+    `controls` is a flat name -> widget-label map, deliberately decoupled
+    from tree paths (which stay literal on each `settings.SettingEntry` in
+    `ibkr_settings.toml`): this dict exists to version-proof against IBKR
+    renaming a *label*, not to describe a setting's navigation.
+
+    `api_precautions_*` covers the API/Precautions panel. The control set is
+    account/permission dependent (e.g. market-data entitlements), so a given
+    deployment may not have every entry here, and a future account could
+    expose controls not listed here.
+
+    `splash_title_marker` matches the splash/"Starting application..." frame
+    that must close before `Configure/Settings` is safely reachable --
+    opening the menu too early can silently fail to open the dialog.
+    `settings.py`'s `open_settings_dialog` waits for this signal first.
+
+    `ok_button` is what `close_settings_dialog` clicks to commit and close
+    the dialog -- `"OK"` has Swing's standard apply-and-close semantics,
+    unlike `"Apply"`, which commits without closing. `apply_button`/
+    `cancel_button` are kept for callers that need those semantics
+    explicitly."""
+
+    gateway_menu_path: str
+    tws_menu_path: str
+    tws_menu_path_classic: str
+    dialog_title_marker: str
+    apply_button: str
+    cancel_button: str
+    ok_button: str
+    splash_title_marker: str
+    controls: dict[str, str]
+
+
+@attrs.define(frozen=True)
+class ShutdownLabels:
+    """The graceful shutdown menu item: Gateway's `File > Close` or TWS's
+    `File > Exit`. See `launcher.clean_shutdown`."""
+
+    gateway_menu_path: str
+    tws_menu_path: str
+
+
+@attrs.define(frozen=True)
+class Labels:
+    login: LoginLabels
+    mfa: MfaLabels
+    existing_session: ExistingSessionLabels
+    accept_incoming_connection: AcceptIncomingConnectionLabels
+    login_failed: LoginFailedLabels
+    too_many_failed_login_attempts: TooManyFailedLoginAttemptsLabels
+    settings: SettingsLabels
+    shutdown: ShutdownLabels
+    dismiss_rules: list[DismissRule] = attrs.field(factory=list)
+
+
+def _deep_merge(base: Mapping[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+    """`override` wins per-field, not per-domain -- a user's file only needs to name
+    the one label that changed, not repeat every sibling field or every other domain
+    untouched."""
+    merged = dict(base)
+    for key, value in override.items():
+        existing = merged.get(key)
+        if isinstance(existing, Mapping) and isinstance(value, Mapping):
+            merged[key] = _deep_merge(existing, value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def _load_bundled_default() -> dict[str, Any]:
+    raw = (
+        resources.files("ibcontroller")
+        .joinpath("data", "labels.json")
+        .read_text(encoding="utf-8")
+    )
+    return json.loads(raw)
+
+
+def load_labels(config_dir: str | Path | None = None) -> Labels:
+    """Loads the bundled default, then merges an optional `{config_dir}/labels.json`
+    override on top if one exists. `config_dir` is typically
+    `app_dirs.resolve_app_dirs()`'s first element -- passed explicitly rather than
+    resolved here, matching
+    `config.py`'s own convention of callers resolving app dirs once and threading the
+    result through."""
+    data = _load_bundled_default()
+    if config_dir is not None:
+        override_path = Path(config_dir) / "labels.json"
+        if override_path.is_file():
+            override_data = json.loads(override_path.read_text(encoding="utf-8"))
+            data = _deep_merge(data, override_data)
+    return converter.structure(data, Labels)