layover 0.1.0.dev0__py3-none-any.whl

layover/oracles/base.py

@@ -0,0 +1,224 @@
+"""The oracle contract (ORACLES §1).
+
+Every source — an API, a scraped site, a punctuality lookup — implements this and
+publishes a capability descriptor. The solver plans against *capabilities*, never
+against site names, so that losing an oracle degrades a search rather than breaking
+it.
+
+Failures are typed, because "no offers" is ambiguous and the ambiguity is dangerous:
+an empty market and a silently broken parser look identical from the outside, and
+only one of them means "stop querying".
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import date
+from enum import StrEnum
+from typing import Any
+
+from layover.models import Cabin, Offer, POSContext, TripShape
+
+
+class FailureKind(StrEnum):
+    BLOCKED = "blocked"
+    """403/429, a bot wall, a login redirect. Hard signal: back off."""
+    CAPTCHA = "captcha"
+    """Never auto-solved. Screenshot, cool down, route around (ORACLES §2)."""
+    PARSE_ERROR = "parse_error"
+    """The response arrived and made no sense — usually a layout change."""
+    EMPTY_ANOMALY = "empty_anomaly"
+    """Zero offers where offers were expected. Soft signal: possible soft block."""
+    EMPTY_MARKET = "empty_market"
+    """Zero offers, believed genuine. Not a failure of the adapter."""
+    TIMEOUT = "timeout"
+    RATE_LIMITED = "rate_limited"
+    """Our own token bucket refused — never the site's problem."""
+    UNSUPPORTED = "unsupported"
+    """The oracle cannot express this query at all."""
+
+
+@dataclass(frozen=True, slots=True)
+class OracleCapabilities:
+    """What an oracle can be asked, and what asking costs."""
+
+    trip_shapes: frozenset[TripShape] = frozenset({TripShape.ONE_WAY, TripShape.RETURN})
+    date_range_query: bool = False
+    """Native calendar/±n pricing — the cheap source of bounds (DESIGN §6)."""
+    nearby_airports: bool = False
+    virtual_interline: bool = False
+    composes_one_ways: bool = False
+    """Whether a "return" from this source is already two one-way tickets.
+
+    AZair's whole business is composing one-ways that no single airline sells
+    together, so asking it the return-versus-one-ways question spends two queries to
+    be told what its baseline answer already contained. A probe that cannot learn
+    anything is not a cheap probe, it is a wasted one (DESIGN §6)."""
+    hidden_city: bool = False
+    multimodal: bool = False
+    baggage_filter: bool = False
+    pos_controls: frozenset[str] = frozenset()
+    """Any of: market_param, currency_param, locale, ip_sensitive."""
+    latency_est_s: float = 3.0
+    block_risk: str = "low"
+    money_cost_per_query: float = 0.0
+    bookable: str = "deep_link"
+    coverage: str = "unknown"
+    """What this source actually knows about, in plain words.
+
+    A capability descriptor that only lists *features* will happily send a Bangkok
+    query to a European low-cost combinator and read the empty answer as a finding.
+    Coverage is a capability too."""
+
+    def can_answer(self, query: OracleQuery) -> bool:
+        return query.trip_shape in self.trip_shapes
+
+
+@dataclass(frozen=True, slots=True)
+class OracleQuery:
+    """One request, in oracle-neutral terms.
+
+    The `dedup_key` is what makes the politeness budget real: two requests with the
+    same key are the same question, and the second one is answered from the session
+    store instead of the network (DESIGN §6).
+    """
+
+    origin: str
+    destination: str
+    depart: date
+    trip_shape: TripShape = TripShape.ONE_WAY
+    return_on: date | None = None
+    adults: int = 1
+    cabin: Cabin = Cabin.ECONOMY
+    pos: POSContext = field(default_factory=POSContext)
+    max_stops: int | None = None
+    baggage_filter: bool = False
+    depart_until: date | None = None
+    """End of the outbound date window, for oracles with `date_range_query`.
+
+    One query covering a range is the cheapest bound the solver ever gets (DESIGN §6):
+    it prices many dates for the cost of one request. Oracles without the capability
+    ignore it and are asked per date."""
+    return_until: date | None = None
+    min_nights: int | None = None
+    max_nights: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.trip_shape is TripShape.RETURN and self.return_on is None:
+            raise ValueError("a return query needs a return date")
+        if self.return_on is not None and self.return_on <= self.depart:
+            raise ValueError("the return date must be after the outbound date")
+
+    @property
+    def dedup_key(self) -> str:
+        payload = {
+            "origin": self.origin.upper(),
+            "destination": self.destination.upper(),
+            "depart": self.depart.isoformat(),
+            "return_on": self.return_on.isoformat() if self.return_on else None,
+            "shape": str(self.trip_shape),
+            "adults": self.adults,
+            "cabin": str(self.cabin),
+            "pos": self.pos.model_dump(),
+            "max_stops": self.max_stops,
+            "baggage_filter": self.baggage_filter,
+            "depart_until": self.depart_until.isoformat() if self.depart_until else None,
+            "return_until": self.return_until.isoformat() if self.return_until else None,
+            "min_nights": self.min_nights,
+            "max_nights": self.max_nights,
+        }
+        blob = json.dumps(payload, sort_keys=True, default=str)
+        return hashlib.sha256(blob.encode()).hexdigest()[:24]
+
+    def describe(self) -> str:
+        leg = f"{self.origin}-{self.destination} {self.depart}"
+        if self.depart_until and self.depart_until != self.depart:
+            leg += f"..{self.depart_until}"
+        if self.return_on:
+            leg += f" / {self.return_on}"
+        if self.return_until and self.return_until != self.return_on:
+            leg += f"..{self.return_until}"
+        if self.min_nights is not None:
+            leg += f" [{self.min_nights}-{self.max_nights}n]"
+        return f"{leg} x{self.adults} {self.cabin} @{self.pos.name}"
+
+
+@dataclass(frozen=True, slots=True)
+class QueryResult:
+    """Offers, or a typed reason there are none."""
+
+    query: OracleQuery
+    oracle_id: str
+    offers: list[Offer] = field(default_factory=list)
+    failure: FailureKind | None = None
+    detail: str = ""
+    latency_ms: float | None = None
+    raw: Any = None
+    """Kept only in memory, for fixture recording and debugging."""
+
+    @property
+    def ok(self) -> bool:
+        return self.failure is None
+
+    @property
+    def status(self) -> str:
+        return "ok" if self.ok else str(self.failure)
+
+    @classmethod
+    def failed(
+        cls,
+        query: OracleQuery,
+        oracle_id: str,
+        kind: FailureKind,
+        detail: str = "",
+        latency_ms: float | None = None,
+    ) -> QueryResult:
+        return cls(
+            query=query,
+            oracle_id=oracle_id,
+            failure=kind,
+            detail=detail,
+            latency_ms=latency_ms,
+        )
+
+
+class Oracle(ABC):
+    """What every source implements."""
+
+    id: str
+    capabilities: OracleCapabilities
+
+    @abstractmethod
+    def search(self, query: OracleQuery) -> QueryResult:
+        """Answer one query, or fail in a way the health monitor can classify."""
+
+    def canary(self) -> QueryResult:
+        """A cheap self-test on a known-liquid route (ORACLES §5).
+
+        Used to decide recovery after a cooldown: if this comes back empty, the
+        adapter is broken rather than the market.
+        """
+        return self.search(self.canary_query())
+
+    def canary_query(self) -> OracleQuery:
+        from datetime import timedelta
+
+        return OracleQuery(
+            origin="BUD",
+            destination="LON",
+            depart=date.today() + timedelta(days=30),
+        )
+
+
+def classify_empty(offers: list[Offer], *, expected_liquid: bool) -> FailureKind | None:
+    """Zero offers: genuinely empty market, or a silent breakage? (ORACLES §3)
+
+    The heuristic is deliberately conservative — on a route that should always have
+    something, "no results" means the adapter, not the world.
+    """
+    if offers:
+        return None
+    return FailureKind.EMPTY_ANOMALY if expected_liquid else FailureKind.EMPTY_MARKET

layover/oracles/consent.py

@@ -0,0 +1,199 @@
+"""Reusing a consent choice you already made (ORACLES §2, §7).
+
+From an EU address Google answers with a consent interstitial, and an HTTP client
+cannot answer it. The design's answer is a browser profile that has *actually* clicked
+the dialog — this module is the small version of that: you make the choice in your own
+browser, once, and layover reuses the resulting cookie the way your browser would.
+
+**What this deliberately is not.** It does not fabricate a consent value, guess one,
+or synthesise "accept all" on your behalf. The value comes from a browser where a
+human answered the dialog; if you have not answered it, there is nothing to import and
+the wall stays up. That distinction is the whole point: the EU obstacle is a consent
+question, and the honest way past a question is to answer it.
+
+It also does not need to be "accept all". Google records a rejection in the same
+cookie, and a rejected-consent cookie clears the interstitial just as well.
+
+Capture it from a **logged-out private window**, not from your everyday browser. The
+value is a stable token, so every request carries the same one; taken from a session
+where you are signed in, it is a token your signed-in browser also holds, and the two
+become correlatable. An incognito window that has never seen your account gives a
+cookie that is merely stable, not linked to you. (A *new Google account* is the wrong
+fix — an account is a far stronger identifier than a cookie, and creating one to
+support automated querying turns a grey area into a plain violation.)
+
+"Reject all" works as well as "accept all": both record a decision, and the decision
+is what clears the interstitial.
+
+    open a private window → google.com → answer the dialog → DevTools →
+    Application → Cookies → copy **SOCS**
+
+    layover consent --import "SOCS=<value>"
+    layover consent --check
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+CONSENT_COOKIES = ("SOCS", "CONSENT")
+"""The cookies Google uses to record the answer. Nothing else is stored."""
+
+
+def default_cookie_path() -> Path:
+    return Path.home() / ".config" / "layover" / "cookies.toml"
+
+
+@dataclass(slots=True)
+class CookieJar:
+    """Per-domain cookies the owner has chosen to share with layover.
+
+    Kept in its own file, gitignored, and holding only consent cookies — never
+    session or authentication cookies. layover logs into nothing (ORACLES §7), so a
+    cookie that would authenticate anything has no business here.
+    """
+
+    path: Path = field(default_factory=default_cookie_path)
+    domains: dict[str, dict[str, str]] = field(default_factory=dict)
+    meta: dict[str, dict[str, str]] = field(default_factory=dict)
+    """Per domain: when it was imported, and which exit it was captured from.
+
+    The exit matters more than it looks. A cookie captured at home and then sent
+    through a Singapore exit is a *more* distinctive combination than either alone —
+    it says "the person whose consent record this is, arriving from an address they
+    have never used". That is the identity-consistency rule in DESIGN §9, and here it
+    is enforced rather than advised."""
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> CookieJar:
+        path = path or default_cookie_path()
+        jar = cls(path=path)
+        if not path.is_file():
+            return jar
+        raw = tomllib.loads(path.read_text())
+        for domain, cookies in (raw.get("domain") or {}).items():
+            jar.domains[domain] = {str(k): str(v) for k, v in cookies.items()}
+        for domain, meta in (raw.get("meta") or {}).items():
+            jar.meta[domain] = {str(k): str(v) for k, v in meta.items()}
+        return jar
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        lines = [
+            "# Cookies you have chosen to share with layover (docs/ORACLES.md §2).",
+            "#",
+            "# Consent choices only — never anything that authenticates you. layover",
+            "# logs into nothing, so a session cookie here would be pure risk.",
+            "# This file is gitignored. Delete it any time; the only cost is that",
+            "# Google goes back to asking.",
+            "",
+        ]
+        for domain, cookies in sorted(self.domains.items()):
+            lines.append(f'[domain."{domain}"]')
+            for name, value in sorted(cookies.items()):
+                lines.append(f'{name} = "{value}"')
+            lines.append("")
+        for domain, meta in sorted(self.meta.items()):
+            lines.append(f'[meta."{domain}"]')
+            for name, value in sorted(meta.items()):
+                lines.append(f'{name} = "{value}"')
+            lines.append("")
+        self.path.write_text("\n".join(lines))
+        self.path.chmod(0o600)
+
+    def for_domain(self, domain: str) -> dict[str, str]:
+        """Cookies for a host, including any stored against a parent domain."""
+        out: dict[str, str] = {}
+        for stored, cookies in self.domains.items():
+            if domain == stored or domain.endswith(f".{stored}"):
+                out.update(cookies)
+        return out
+
+    def set(
+        self,
+        domain: str,
+        name: str,
+        value: str,
+        *,
+        captured_egress: str | None = None,
+    ) -> None:
+        self.domains.setdefault(domain, {})[name] = value
+        meta = self.meta.setdefault(domain, {})
+        meta["imported_at"] = datetime.now(UTC).isoformat(timespec="seconds")
+        if captured_egress:
+            meta["captured_egress"] = captured_egress
+
+    def captured_egress(self, domain: str) -> str | None:
+        for stored, meta in self.meta.items():
+            if domain == stored or domain.endswith(f".{stored}"):
+                return meta.get("captured_egress")
+        return None
+
+    def age_days(self, domain: str) -> int | None:
+        """How old the stored answer is. Consent records do not live forever."""
+        for stored, meta in self.meta.items():
+            if domain == stored or domain.endswith(f".{stored}"):
+                stamp = meta.get("imported_at")
+                if not stamp:
+                    return None
+                return (datetime.now(UTC) - datetime.fromisoformat(stamp)).days
+        return None
+
+    def usable_for(
+        self, domain: str, *, egress: str | None, max_age_days: int = 365
+    ) -> tuple[dict[str, str], list[str]]:
+        """Cookies to send, plus every reason not to trust them.
+
+        Returns no cookies at all on an egress mismatch. Sending them anyway would
+        trade a consent wall — a visible, recoverable failure — for a distinctive
+        fingerprint, which is neither.
+        """
+        cookies = self.for_domain(domain)
+        if not cookies:
+            return {}, []
+
+        problems: list[str] = []
+        captured = self.captured_egress(domain)
+        if captured and egress and captured != egress:
+            problems.append(
+                f"captured from {captured} but this request leaves from {egress} — "
+                f"not sending it: that pairing is more identifying than either alone"
+            )
+            return {}, problems
+
+        age = self.age_days(domain)
+        if age is not None and age > max_age_days:
+            problems.append(
+                f"imported {age} days ago; consent records typically lapse around a "
+                f"year, so re-import if the wall comes back"
+            )
+        return cookies, problems
+
+
+class NotAConsentCookie(ValueError):
+    """Refuses anything that is not a consent cookie."""
+
+
+def parse_cookie(text: str) -> tuple[str, str]:
+    """Read a `NAME=value` pair, and accept only consent cookies.
+
+    The refusal matters more than the parsing: pasting a whole `Cookie:` header from a
+    logged-in browser would hand over session credentials, and this tool has no use
+    for them.
+    """
+    if "=" not in text:
+        raise NotAConsentCookie(f"expected NAME=value, got {text[:40]!r}")
+    name, _, value = text.strip().partition("=")
+    name, value = name.strip(), value.strip().strip('"')
+    if name.upper() not in CONSENT_COOKIES:
+        raise NotAConsentCookie(
+            f"{name} is not a consent cookie. Only {', '.join(CONSENT_COOKIES)} are "
+            f"accepted — layover logs into nothing and must not hold anything that "
+            f"authenticates you."
+        )
+    if not value:
+        raise NotAConsentCookie(f"{name} has no value")
+    return name.upper(), value

layover/oracles/knowledge.py

@@ -0,0 +1,208 @@
+"""What we have learned about oracles, kept across sessions (DESIGN §5).
+
+Session stores age out after a fortnight, which is right for prices and wrong for
+everything else. Two kinds of fact outlive them:
+
+* **Coverage.** AZair does not fly to Bangkok. That is a property of the oracle, not
+  of a search, and re-learning it costs a query every time a session starts fresh.
+* **Health.** Backoff is meaningless if it forgets: an oracle that blocked us an hour
+  ago should still be cooling now, whatever process is asking (ORACLES §5).
+
+Both are deliberately *small* and *non-price*. Nothing here records a fare, so the
+no-hoarding principle is untouched — this is a notebook about the sources, not about
+the market.
+
+Coverage facts expire. Airlines add routes and sites extend their networks, so a
+"not covered" from six months ago is a stale opinion rather than a fact; the default
+shelf life is 90 days, after which the question is worth one query again.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+DEFAULT_COVERAGE_TTL_DAYS = 90
+
+
+def default_path() -> Path:
+    return Path.home() / ".local" / "state" / "layover" / "oracle-knowledge.json"
+
+
+@dataclass(frozen=True, slots=True)
+class CoverageFact:
+    oracle_id: str
+    route: str
+    covered: bool
+    learned_at: datetime
+    detail: str = ""
+
+    def age_days(self, now: datetime | None = None) -> int:
+        return ((now or datetime.now(UTC)) - self.learned_at).days
+
+    def is_stale(
+        self, ttl_days: int = DEFAULT_COVERAGE_TTL_DAYS, now: datetime | None = None
+    ) -> bool:
+        return self.age_days(now) >= ttl_days
+
+    def describe(self) -> str:
+        verdict = "covers" if self.covered else "does not cover"
+        return f"{self.oracle_id} {verdict} {self.route} (learned {self.age_days()}d ago)"
+
+
+class OracleKnowledge:
+    """A small, durable notebook about the sources."""
+
+    def __init__(
+        self, path: Path | None = None, *, ttl_days: int = DEFAULT_COVERAGE_TTL_DAYS
+    ) -> None:
+        self.path = Path(path or default_path())
+        self.ttl_days = ttl_days
+        self._data: dict[str, Any] = self._load()
+
+    def _load(self) -> dict[str, Any]:
+        if not self.path.is_file():
+            return {"coverage": {}, "health": {}}
+        try:
+            raw = json.loads(self.path.read_text())
+        except json.JSONDecodeError:
+            return {"coverage": {}, "health": {}}  # corrupt notebook: start a new one
+        raw.setdefault("coverage", {})
+        raw.setdefault("health", {})
+        return raw
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(self._data, indent=2, sort_keys=True))
+
+    # ── coverage ─────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _key(oracle_id: str, route: str) -> str:
+        return f"{oracle_id}|{route.upper()}"
+
+    def record_coverage(
+        self,
+        oracle_id: str,
+        route: str,
+        *,
+        covered: bool,
+        detail: str = "",
+        when: datetime | None = None,
+    ) -> None:
+        """Remember whether a source can answer about a route at all."""
+        self._data["coverage"][self._key(oracle_id, route)] = {
+            "oracle_id": oracle_id,
+            "route": route.upper(),
+            "covered": covered,
+            "learned_at": (when or datetime.now(UTC)).isoformat(timespec="seconds"),
+            "detail": detail[:200],
+        }
+        self.save()
+
+    def coverage(self, oracle_id: str, route: str) -> CoverageFact | None:
+        entry = self._data["coverage"].get(self._key(oracle_id, route))
+        if not entry:
+            return None
+        try:
+            learned = datetime.fromisoformat(entry["learned_at"])
+        except (KeyError, ValueError):
+            return None
+        return CoverageFact(
+            oracle_id=entry["oracle_id"],
+            route=entry["route"],
+            covered=bool(entry["covered"]),
+            learned_at=learned,
+            detail=entry.get("detail", ""),
+        )
+
+    def excluded_for(self, route: str, *, now: datetime | None = None) -> set[str]:
+        """Oracles known not to cover this route, ignoring stale opinions."""
+        out: set[str] = set()
+        for entry in self._data["coverage"].values():
+            if entry.get("route") != route.upper() or entry.get("covered"):
+                continue
+            fact = self.coverage(entry["oracle_id"], entry["route"])
+            if fact and not fact.is_stale(self.ttl_days, now):
+                out.add(fact.oracle_id)
+        return out
+
+    def known_gaps(self) -> list[CoverageFact]:
+        facts = []
+        for entry in self._data["coverage"].values():
+            fact = self.coverage(entry.get("oracle_id", ""), entry.get("route", ""))
+            if fact and not fact.covered and not fact.is_stale(self.ttl_days):
+                facts.append(fact)
+        return sorted(facts, key=lambda f: (f.oracle_id, f.route))
+
+    # ── health ───────────────────────────────────────────────────────────────
+
+    def record_failure(
+        self,
+        oracle_id: str,
+        kind: str,
+        *,
+        cooldown_minutes: float = 0.0,
+        when: datetime | None = None,
+    ) -> None:
+        """Note a failure, and when this oracle may be asked again.
+
+        Backoff that forgets is not backoff: an oracle blocked ten minutes ago is
+        still blocked now, whichever process is asking.
+        """
+        now = when or datetime.now(UTC)
+        entry = self._data["health"].get(oracle_id, {})
+        entry["last_failure"] = kind
+        entry["last_failure_at"] = now.isoformat(timespec="seconds")
+        entry["consecutive_failures"] = int(entry.get("consecutive_failures", 0)) + 1
+        if cooldown_minutes > 0:
+            entry["cooling_until"] = (now + timedelta(minutes=cooldown_minutes)).isoformat(
+                timespec="seconds"
+            )
+        self._data["health"][oracle_id] = entry
+        self.save()
+
+    def record_success(self, oracle_id: str, when: datetime | None = None) -> None:
+        entry = self._data["health"].get(oracle_id, {})
+        entry["consecutive_failures"] = 0
+        entry["cooling_until"] = None
+        entry["last_success_at"] = (when or datetime.now(UTC)).isoformat(timespec="seconds")
+        self._data["health"][oracle_id] = entry
+        self.save()
+
+    def cooling(self, oracle_id: str, *, now: datetime | None = None) -> datetime | None:
+        """When this oracle may be asked again, or `None` if it is free to use."""
+        entry = self._data["health"].get(oracle_id) or {}
+        stamp = entry.get("cooling_until")
+        if not stamp:
+            return None
+        try:
+            until = datetime.fromisoformat(stamp)
+        except ValueError:
+            return None
+        return until if until > (now or datetime.now(UTC)) else None
+
+    def health(self, oracle_id: str) -> dict[str, Any]:
+        return dict(self._data["health"].get(oracle_id) or {})
+
+    # ── maintenance ──────────────────────────────────────────────────────────
+
+    def forget(self, oracle_id: str) -> int:
+        """Drop everything remembered about one source; returns how much was dropped.
+
+        The escape hatch for when the notebook is wrong — a fixed adapter, a site that
+        extended its network, a cooldown that has clearly outlived its cause.
+        """
+        keys = [k for k, v in self._data["coverage"].items() if v.get("oracle_id") == oracle_id]
+        for key in keys:
+            del self._data["coverage"][key]
+        dropped = len(keys) + (1 if self._data["health"].pop(oracle_id, None) else 0)
+        self.save()
+        return dropped
+
+    def oracles(self) -> list[str]:
+        names = {entry.get("oracle_id", "") for entry in self._data["coverage"].values()}
+        return sorted(n for n in names | set(self._data["health"]) if n)