Skip to content

"Vibe-Trading: Your Personal Trading Agent"

8.4 KB
Raw Blame
"""Allowlist registry for internal scheduled callables (scheduler unification).

The ONLY name→callable mapping available to ``executor_kind == "internal"``
jobs. Security contract — this is the safety bedrock, "no arbitrary shell,
no dynamic import":

* Keys are literal strings registered in THIS module. The production surface
  is the explicit ``_INTERNAL_CALLABLES`` dict at the bottom, populated by
  module edit only. Nothing in a request path (HTTP body, job file free
  text, environment variable) may ever register a callable;
  :func:`register_internal` exists for module edits and tests.
* Resolution is an exact-key dict lookup. There is NO dynamic resolution of
  any kind: names are never parsed as import paths, never turned into code,
  and never walked through attribute chains. A name that happens to be a
  real import path (a stdlib process-spawning function, say) resolves to
  nothing unless that exact string is a registered key — the registry's
  name space and Python's import space are fully isolated.
* Malformed names are rejected before any lookup: the shape allowlist
  (dotted identifiers only) fails every separator, ``..``, whitespace and
  shell-metacharacter form by construction.
* Values are callables taking no required arguments, sync or async. The run
  contract lives on the executor side (see
  :mod:`src.scheduled_research.internal_dispatch`): sync callables are
  offloaded through ``asyncio.to_thread``, async callables are awaited
  directly, always in a background task — never on the serialized tick loop.
* Domain imports are DEFERRED: each production entry is a literal zero-arg
  wrapper whose body imports the domain callable at first firing. This
  module is imported by the generic :mod:`src.scheduling` package (and,
  through it, by ``scheduled_research.models``), so a top-level domain
  import here would drag the whole ``br_data``/``memory`` stack into every
  process that merely touches the scheduling vocabulary — and invert the
  dependency direction of the generic kernel. The wrappers keep the dict
  literal-keyed and exact-match-only; the deferred import is a fixed module
  statement inside a function body, never a name-driven resolution.
"""

from __future__ import annotations

import re
from typing import Awaitable, Callable

#: A registered internal callable: invoked with no arguments, either sync
#: (return value discarded) or async. ``...`` tolerates defaulted/optional
#: parameters; the run contract above is what the executor guarantees.
InternalRunnable = Callable[..., Awaitable[None] | None]

#: Dotted-identifier shape allowlist, e.g. ``memory.consolidate``. Being an
#: allowlist (not a denylist) is the point: path separators, ``..``, ``:``,
#: whitespace and shell metacharacters (``; | & $ < > ( )`` and backtick)
#: fail the shape check by construction and never reach the dict.
_VALID_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$")


class InternalCallableError(KeyError):
    """A name cannot be resolved to a registered internal callable.

    Subclasses :class:`KeyError` so consumers may catch either; ``__str__``
    is overridden because :class:`KeyError` would otherwise ``repr()`` the
    message and quote it.
    """

    def __str__(self) -> str:
        return str(self.args[0]) if self.args else ""


def _check_name(name: object) -> str:
    """Return *name* if it has the dotted-identifier shape, else reject it."""
    if not isinstance(name, str) or not _VALID_NAME_RE.fullmatch(name):
        raise InternalCallableError(
            f"internal callable name {name!r} is rejected: only dotted identifiers "
            "(letters, digits, '_', single '.' separators) are allowed"
        )
    return name


def register_internal(name: str, fn: InternalRunnable, *, replace: bool = False) -> None:
    """Register *fn* under the literal key *name*.

    MODULE/TEST-ONLY: the production surface is the explicit dict entries at
    the bottom of this module, added by module edit. No runtime input may
    reach this function — the invariant is documented here and guarded by
    ``test_registry.py``.

    Args:
        name: Literal registry key (dotted-identifier shape).
        fn: Zero-required-arg callable, sync or async.
        replace: Allow overwriting an existing key. Off by default so a
            production entry is never silently clobbered.

    Raises:
        InternalCallableError: *name* is malformed, or already registered
            without ``replace=True``.
        TypeError: *fn* is not callable.
    """
    key = _check_name(name)
    if not callable(fn):
        raise TypeError(f"internal callable {key!r} requires a callable, got {type(fn).__name__}")
    if not replace and key in _INTERNAL_CALLABLES:
        raise InternalCallableError(f"internal callable {key!r} is already registered")
    _INTERNAL_CALLABLES[key] = fn


def resolve_internal(name: str) -> InternalRunnable:
    """Return the callable registered under the EXACT key *name*.

    Exact-key dict lookup only — never a prefix match, never a parse, never
    a fallback to Python's import machinery.

    Args:
        name: Registry key from a job's ``internal_callable`` field.

    Returns:
        The registered callable object (identity preserved).

    Raises:
        InternalCallableError: *name* is malformed (rejected before lookup)
            or is not a registered key; the message for an unregistered
            well-formed name lists every registered name.
    """
    key = _check_name(name)
    try:
        return _INTERNAL_CALLABLES[key]
    except KeyError:
        raise InternalCallableError(
            f"internal callable {key!r} is not registered; registered names: {list_internal()}"
        ) from None


def list_internal() -> tuple[str, ...]:
    """Return every registered key, sorted."""
    return tuple(sorted(_INTERNAL_CALLABLES))


def is_registered(name: object) -> bool:
    """Whether *name* is a well-formed AND registered key. Never raises."""
    return isinstance(name, str) and bool(_VALID_NAME_RE.fullmatch(name)) and name in _INTERNAL_CALLABLES


# ---------------------------------------------------------------------------
# Production entries — literal zero-arg wrappers with a deferred domain
# import inside the function body (module docstring, "Domain imports are
# DEFERRED"). The wrapper is the registered callable object; the import it
# performs is a fixed statement, never derived from the registry key.
# ---------------------------------------------------------------------------


def _memory_consolidate() -> None:
    """Run one scheduled memory-consolidation pass (deferred domain import).

    Backs the ``memory.consolidate`` key: daily archive-only consolidation,
    opt-in via ``VT_MEMORY_CONSOLIDATION`` and an honest no-op unless
    ``VT_MEMORY_GC`` is on too (see :mod:`src.memory.consolidation`).
    """
    from src.memory.consolidation import consolidate

    consolidate()


def _br_data_run_sync() -> None:
    """Run one Brazilian official-dataset sync (deferred domain import).

    Backs the ``br_data.run_sync`` key: daily sync, opt-in via
    ``VIBE_BR_SYNC_ENABLED``; replaces the retired ``src.br_data`` daemon —
    Per-source errors become a failed scheduled attempt, so the executor
    records the failure and applies its existing retry budget.
    """
    from src.br_data.sync import run_sync

    report = run_sync()
    failed = sorted(
        name for name, outcome in report.items()
        if isinstance(outcome, dict) and "error" in outcome
    )
    if failed:
        # Report source names only; upstream diagnostics can carry local
        # paths or credentials and must not be copied into the job store.
        raise RuntimeError(f"Brazilian dataset sync failed for: {', '.join(failed)}")


# ---------------------------------------------------------------------------
# Production allowlist — the ONLY name→callable surface (module docstring).
#
# A new entry is ONE literal wrapper function above plus ONE literal key
# here. Rules: literal keys only; values are the wrapper callable objects,
# never import-path strings; nothing populates this dict from runtime input.
# An internal firing whose key is missing fail-closes into the executor's
# dispatch-failure path (``failure_kind="dispatch"``).
# ---------------------------------------------------------------------------
_INTERNAL_CALLABLES: dict[str, InternalRunnable] = {
    "memory.consolidate": _memory_consolidate,
    "br_data.run_sync": _br_data_run_sync,
}