snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/contrib/config.py

@@ -0,0 +1,264 @@
+"""SHARED translators: from a framework's native config (dicts) to the centralised config.
+
+The logic has NOTHING of any concrete framework in it —it is dict → `SnakeConnectionConfig` /
+(channels, panel config)—, so it lives here and `contrib.django`, the only framework linker, uses
+it. The TypedDicts type the SHAPE of the dict the user writes, for IntelliSense. Everything fails
+LOUD: an unknown `ENGINE`/channel or a non-numeric threshold blows up naming them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NotRequired, TypedDict
+
+from snakeorm.advisor import DEFAULT_MIN_MS
+from snakeorm.connection import SnakeBackend, SnakeConnectionConfig
+from snakeorm.core.exceptions import SnakeConfigError
+from snakeorm.debug import (
+    AsyncCaptureDriver,
+    CaptureDriver,
+    SnakeDebugChannel,
+    SnakeDebugConfig,
+    SnakeDebugLanguage,
+    parse_channels,
+)
+
+if TYPE_CHECKING:
+    from snakeorm.session import AsyncSession, SnakeSession
+
+
+def open_session(config: SnakeConnectionConfig) -> SnakeSession:
+    """Open a session from the central config, with the captured driver (the panel sees the SQL).
+
+    The UNIVERSAL path: whoever builds a `SnakeConnectionConfig` directly (Flask, FastAPI, or
+    wherever) injects it into their app and opens with this. A framework WITHOUT a connection
+    convention needs no bespoke linker —only Django has one, because its `DATABASES` IS a convention
+    to translate—.
+
+    The `backend` also DECLARES the engine to the capture driver, so every record knows which engine
+    ran it — `db.system.name`, which the `otel` channel puts on every query span. It is declared and
+    not guessed: a pooled or timed-out driver hides its class, and no SQL tells MySQL from MariaDB.
+    """
+    system = config.backend.db_system_name
+    return config.open(wrap=lambda driver: CaptureDriver(driver, system=system))
+
+
+async def open_session_async(config: SnakeConnectionConfig) -> AsyncSession:
+    """The same path, awaited: an ASYNCHRONOUS session from the central config with the SQL captured.
+
+    It exists for the same reason as its sibling: an async framework building a
+    `SnakeConnectionConfig` had to assemble driver and dialect by hand, and lost the debug panel
+    along the way. That the facade is a single line is precisely the sign that the seam was in the
+    right place.
+
+    The engine is declared here too: one seam, the same two colours.
+    """
+    system = config.backend.db_system_name
+    return await config.open_async(
+        wrap=lambda driver: AsyncCaptureDriver(driver, system=system)
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeOrmConfig:
+    """SnakeORM's ROOT config in ONE object: the connections (`databases`) and the panel settings.
+
+    The user builds ONE, injects it into their app (Flask `app.config`, FastAPI `app.state`, ...)
+    and out of it come the sessions (`open`), the panel config (`channels` / `debug_config`) and the
+    migrations (`migrate`). Multi-DB by name in `databases`; `debug` are the channels
+    (`"ssr,envelope,timing"`) and `advise_ms` the advisor threshold. `migrations_dir` decides WHERE
+    the migrations live: a SINGLE directory (centralised) if declared, or `None` for the per-domain
+    mode (one `migrations/` per domain). `language` fixes the language the panel OPENS in (default
+    English; the user changes it with the 🌐 selector). The debug envelope
+    (`snakeorm` in the JSON) is turned on by the `envelope` CHANNEL of `debug`, not by a separate
+    flag. It is the FRIENDLY face: one object, everything inside, typed. SnakeORM reads THIS object,
+    never the `.env`: each framework reads its environment its own way and fills this in.
+    """
+
+    databases: Mapping[str, SnakeConnectionConfig]
+    debug: str = ""
+    advise_ms: float = DEFAULT_MIN_MS
+    migrations_dir: str | None = None
+    language: SnakeDebugLanguage = SnakeDebugLanguage.EN
+    production: bool | None = None
+    """WHERE this app runs. Declaring it is what lets the risky channels be dropped.
+
+    `None` means NOBODY SAID, which is a third state and not a synonym for development: while
+    `debug` names no channel that hands out SQL it costs nothing, and the moment one is named the
+    middleware refuses to start rather than guessing. This is the root config, so it is the one
+    place a whole app answers the question once — and the reason it is a typed field rather than a
+    key in a settings dict is the one `SnakeDebugConfig` gives: a dict returns `object` on every
+    access and reintroduces the `Any` the thesis forbids.
+
+    A Django app does not need it: that adapter reads `settings.DEBUG`, which is the framework's own
+    answer to the same question.
+    """
+
+    def _connection(self, alias: str) -> SnakeConnectionConfig:
+        """The connection that alias names, or a `SnakeError` saying which ones exist.
+
+        It used to be `self.databases[alias]` bare, in two places. A `KeyError: 'analitycs'` does
+        not say what aliases there are, does not say where they are declared, and is not even a
+        `SnakeError` — so an application catching `SnakeError` around its start-up did not catch it.
+
+        The answer already existed twelve lines below, in `_backend_for`, with "fail loud: a typo
+        never falls back to a default" written on it. Three places, one question; now one answer.
+        """
+        try:
+            return self.databases[alias]
+        except KeyError:
+            declared = ", ".join(sorted(self.databases)) or "(none)"
+            raise SnakeConfigError(
+                f"'{alias}' is not a connection of this config. The ones it declares are: "
+                f"{declared}. A connection cannot be created from the command line: it has to be "
+                f"in `databases`."
+            ) from None
+
+    def open(self, alias: str = "default") -> SnakeSession:
+        """Open a session of the `alias` connection, with the captured driver (the panel sees the SQL)."""
+        return open_session(self._connection(alias))
+
+    def migrate(self, alias: str = "default") -> list[str]:
+        """Apply the migrations to the `alias` connection. It returns the freshly applied ones.
+
+        MULTI-ENGINE: driver and dialect come out of the `backend`, so it runs on
+        SQLite/Postgres/MySQL alike (the CLI pairs them the same way). Idempotent. Two modes
+        depending on `migrations_dir`:
+
+        - A SINGLE directory (centralised): applied in its linear order.
+        - `None` (PER DOMAIN): it discovers the `apps/*/migrations`, loads them ALL and orders them
+          by FK DEPENDENCY (`accounts` creates `users` → it goes before `blog`, which references
+          it). The order is DERIVED from the relations, not declared by hand.
+        """
+        from snakeorm.migration import (  # lazy: do not drag migration in if you do not migrate
+            MigrationRunner,
+            dependency_order,
+            load,
+        )
+
+        # The alias is resolved FIRST. It used to be indexed at the end, so a typo in an argument
+        # cost a full directory walk and a topological sort of every migration before failing —
+        # and the failure was still a bare `KeyError`.
+        connection = self._connection(alias)
+
+        if self.migrations_dir is not None:
+            pending = load(self.migrations_dir)
+        else:
+            import glob
+
+            dirs = sorted(glob.glob("apps/*/migrations"))
+            if not dirs:
+                raise SnakeConfigError(
+                    "Per-domain mode (`migrations_dir=None`): there are no migrations in `apps/*/migrations`. "
+                    "Generate the ones for each domain (`makemigrations --only`) or declare a single directory."
+                )
+            pending = dependency_order([mig for d in dirs for mig in load(d)])
+
+        driver, dialect = connection.driver_and_dialect()
+        try:
+            return MigrationRunner(driver, dialect).apply(pending)
+        finally:
+            driver.close()
+
+    def channels(self) -> frozenset[SnakeDebugChannel]:
+        """The panel channels (it parses `debug`; fail loud if a channel has a typo)."""
+        return parse_channels(self.debug)
+
+    def debug_config(self) -> SnakeDebugConfig:
+        """The panel config: the advisor threshold, the language it opens in, and the environment."""
+        return SnakeDebugConfig(
+            advise_min_ms=self.advise_ms,
+            language=self.language,
+            production=self.production,
+        )
+
+
+class SnakeOrmDatabase(TypedDict):
+    """The SHAPE of a `DATABASES["<alias>"]` SnakeORM understands (TypedDict = it types a dict literal).
+
+    `ENGINE` accepts the short name (`"postgres"`) or Django's
+    (`"django.db.backends.postgresql"`). The network pieces are optional (SQLite only uses `NAME`,
+    which is the path of the file).
+    """
+
+    ENGINE: str
+    NAME: str
+    HOST: NotRequired[str]
+    PORT: NotRequired[str]
+    USER: NotRequired[str]
+    PASSWORD: NotRequired[str]
+
+
+class SnakeOrmSettings(TypedDict):
+    """The SHAPE of the PANEL config constant (not the connection).
+
+    `DEBUG` are the channels (`"ssr,envelope,timing"`; the `envelope` channel puts the debug in the
+    JSON); `ADVISE_MS`, the index advisor threshold; `LANG` (`"es"`/`"en"`), the language the panel
+    OPENS in. All optional: without `DEBUG` the panel stays off; without `ADVISE_MS`, the default
+    threshold; without `LANG`, English.
+    """
+
+    DEBUG: NotRequired[str]
+    ADVISE_MS: NotRequired[float]
+    LANG: NotRequired[str]
+
+
+# Accepted engine names → backend. It includes Django's so that its `DATABASES` changes nothing.
+_ENGINES: dict[str, SnakeBackend] = {
+    "postgres": SnakeBackend.POSTGRES,
+    "postgresql": SnakeBackend.POSTGRES,
+    "django.db.backends.postgresql": SnakeBackend.POSTGRES,
+    "sqlite": SnakeBackend.SQLITE,
+    "sqlite3": SnakeBackend.SQLITE,
+    "django.db.backends.sqlite3": SnakeBackend.SQLITE,
+    "mysql": SnakeBackend.MYSQL,
+    "django.db.backends.mysql": SnakeBackend.MYSQL,
+}
+
+
+def _backend_for(engine: str) -> SnakeBackend:
+    """Resolve the `ENGINE` to the backend, or BLOW UP naming it (fail loud: a typo never falls back to a default)."""
+    key = engine.strip().lower()
+    try:
+        return _ENGINES[key]
+    except KeyError:
+        valid = ", ".join(sorted({b.value for b in SnakeBackend}))
+        raise SnakeConfigError(
+            f"Unknown ENGINE: '{engine}'. SnakeORM accepts: {valid} "
+            f"(or the 'django.db.backends.*' equivalent)."
+        ) from None
+
+
+def connection_from_mapping(db: SnakeOrmDatabase) -> SnakeConnectionConfig:
+    """Translate a connection dict (`DATABASES` format) into the centralised config."""
+    return SnakeConnectionConfig(
+        backend=_backend_for(db["ENGINE"]),
+        name=str(db["NAME"]),
+        host=db.get("HOST", "localhost"),
+        port=db.get("PORT", ""),
+        user=db.get("USER", ""),
+        password=db.get("PASSWORD", ""),
+    )
+
+
+def debug_config_from_mapping(
+    settings: SnakeOrmSettings,
+) -> tuple[frozenset[SnakeDebugChannel], SnakeDebugConfig]:
+    """Translate the panel config dict into (channels, config). Fail loud if anything is off.
+
+    A channel with a typo or a non-numeric `ADVISE_MS` BLOW UP naming them: a panel that does not
+    start —or a threshold that gets ignored— in silence is precisely the failure being fought.
+    """
+    channels = parse_channels(
+        settings.get("DEBUG", "")
+    )  # an unknown channel → SnakeConfigError
+    raw = settings.get("ADVISE_MS", DEFAULT_MIN_MS)
+    try:
+        advise_min_ms = float(raw)
+    except (TypeError, ValueError):
+        raise SnakeConfigError(f"ADVISE_MS has to be a number, got {raw!r}.") from None
+    return channels, SnakeDebugConfig(
+        advise_min_ms=advise_min_ms,
+        language=SnakeDebugLanguage.coerce(settings.get("LANG")),
+    )

snakeorm/contrib/deliver.py

@@ -0,0 +1,256 @@
+"""PURE core of the debug delivery: headers, envelope and the production gate, in pure functions.
+
+The adapters (ASGI/WSGI/Django) are thin plumbing that calls in here: the logic gets tested and is not duplicated; only the irreducible difference (ASGI ≠ WSGI) stays at the edge.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from snakeorm.advisor import index_hints_from_records
+from snakeorm.core.exceptions import SnakeConfigError
+from snakeorm.debug import (
+    PRODUCTION_ENV_KEY,
+    RISKY_CHANNELS,
+    DebugReport,
+    SnakeDebugChannel,
+    SnakeDebugConfig,
+    SnakeDebugLanguage,
+    render_report_html,
+    render_report_page,
+)
+from snakeorm.migration import current_schema
+
+
+SIDECAR_UNKNOWN_TOKEN_BODY = (
+    b"Unknown debug token: this report is no longer buffered. The sidecar keeps only the most "
+    b"recent reports, so reload the page that produced it to get a fresh token."
+)
+"""The 404 body for `/__snake__/{token}` when the report is gone, for the THREE adapters.
+
+It lives here and not in each adapter for the same reason everything else in this module does: three
+copies of one sentence drift, and this one had already drifted into Spanish (`token desconocido`) in
+all three at once — a body a person reads in their browser, in `contrib/`, outside the single
+bilingual exemption, which covers the debug PANEL. These adapters serve no `SnakeDebugLanguage`
+selector, which is precisely the reasoning that took `debug/channel.py` out of that exemption.
+
+And it says what happened, not just that something did: whoever lands here is holding a stale tab,
+and the two words it used to carry never told them to reload.
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class SidecarPage:
+    """What `/__snake__/{token}` answers: the status, the content type and the body.
+
+    One shape for the three adapters, so the decision of WHAT to answer is taken once and each of
+    them is left with the only thing that really differs: how its protocol writes a response.
+    """
+
+    status: int
+    content_type: str
+    body: bytes
+
+
+def serve_sidecar(
+    report: DebugReport | None,
+    *,
+    accept: str = "",
+    language: SnakeDebugLanguage = SnakeDebugLanguage.EN,
+) -> SidecarPage:
+    """Answer a sidecar token: the panel page to a browser, the report itself to `Accept: application/json`.
+
+    The URL has TWO readers. A person opens it and wants the panel. The history tab holds a token
+    off a response whose body it never sees —an HTML fragment carries its report in the headers— and
+    wants the report; handing it a document that embeds the whole panel would make it parse markup
+    to recover data the server already has as a dictionary.
+
+    The JSON body is `DebugReport.to_dict()`, the very dictionary the `envelope` channel hangs off
+    JSON responses, so the tab reads ONE shape whichever channel brought it.
+
+    The 404 does NOT negotiate: there is one sentence for an evicted report, and a second
+    serialisation of it would be a second wording to keep in step.
+    """
+    if report is None:
+        return SidecarPage(404, "text/plain; charset=utf-8", SIDECAR_UNKNOWN_TOKEN_BODY)
+    if "application/json" in accept:
+        body = json.dumps(report.to_dict(), ensure_ascii=False).encode()
+        return SidecarPage(200, "application/json; charset=utf-8", body)
+    page = render_report_page(report, language=language).encode()
+    return SidecarPage(200, "text/html; charset=utf-8", page)
+
+
+def resolve_production(
+    explicit: bool | None,
+    config: SnakeDebugConfig,
+    channels: frozenset[SnakeDebugChannel],
+) -> bool:
+    """WHERE this process runs: the explicit argument, then the config, then a REFUSAL.
+
+    The order is deliberate. Somebody already passing `production=` keeps the last word; otherwise
+    the config answers (from code or from `SNAKE_ORM_PRODUCTION`); and if nobody said anything, the
+    answer depends on what is at stake. With no risky channel on there is no SQL to leak, so silence
+    resolves to development and costs nothing. With one on, the middleware refuses to start.
+
+    What is NOT here is a default of `False`, and that absence is the whole point. The channels read
+    themselves out of the environment while this one sat next to them defaulting to the permissive
+    answer — two switches for one decision, and the manual one wrong-way-round. The project's own
+    rule is that a typo never falls back to a default; this is that rule applied to the switch that
+    decides whether the SQL goes out on the response.
+    """
+    if explicit is not None:
+        return explicit
+    if config.production is not None:
+        return config.production
+    risky = channels & RISKY_CHANNELS
+    if risky:
+        names = ", ".join(sorted(channel.value for channel in risky))
+        raise SnakeConfigError(
+            f"These debug channels hand the SQL to whoever asked ({names}) and nothing declares "
+            f"whether this is production. Set {PRODUCTION_ENV_KEY}=true|false, or pass "
+            f"production=True/False (or SnakeDebugConfig(production=...)). There is no default: "
+            f"guessing 'development' here is how a deploy serves its statements, with the values "
+            f"already substituted, to anyone who asks for a page."
+        )
+    return False
+
+
+def allowed_channels(
+    channels: frozenset[SnakeDebugChannel],
+    *,
+    production: bool,
+) -> frozenset[SnakeDebugChannel]:
+    """Filter the channels by environment: in production the ones exposing SQL are dropped, even if requested (attack surface)."""
+    if not production:
+        return channels
+    return channels - RISKY_CHANNELS
+
+
+def index_advice(
+    report: DebugReport, config: SnakeDebugConfig
+) -> tuple[tuple[str, str, float], ...]:
+    """Index suggestions for the SLOW queries of the report: the advisor over the SQL + the metadata.
+
+    It only looks at queries above `config.advise_min_ms` (the user's threshold, or 10 ms by
+    default): a fast query over an unindexed column does not deserve an index. Empty if nothing slow
+    filtered.
+    """
+    if not report.records:
+        return ()
+    rows = [(record.sql, record.duration_ms) for record in report.records]
+    return tuple(
+        index_hints_from_records(rows, current_schema(), min_ms=config.advise_min_ms)
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class Delivery:
+    """What to do with the response: headers to add and, if applicable, the `snakeorm` block to inject."""
+
+    headers: tuple[tuple[str, str], ...]
+    envelope: dict[str, object] | None
+
+
+def plan_delivery(
+    report: DebugReport,
+    channels: frozenset[SnakeDebugChannel],
+    *,
+    token: str | None = None,
+) -> Delivery:
+    """Decide headers and envelope from the channels that are on (framework-agnostic).
+
+    The envelope comes out IF the `envelope` channel was requested: the channel itself is the
+    switch (if you declare it in `DEBUG`, you want it). In production `allowed_channels` already
+    removes it, so nothing leaks.
+    """
+    headers: list[tuple[str, str]] = []
+    if SnakeDebugChannel.TIMING in channels:
+        headers.append(("Server-Timing", report.to_server_timing()))
+    if SnakeDebugChannel.SIDECAR in channels and token is not None:
+        headers.append(("X-Debug-Token", token))
+    envelope = report.to_dict() if SnakeDebugChannel.ENVELOPE in channels else None
+    return Delivery(tuple(headers), envelope)
+
+
+def inject_envelope(body: bytes, envelope: dict[str, object]) -> bytes:
+    """Hang the debug (`snakeorm`) off the JSON body, without corrupting it or over-nesting it.
+
+    If the body is already an OBJECT, it is enough to ADD the `snakeorm` key as a sibling (it keeps
+    its shape, with no extra wrapping). If it is an ARRAY or a scalar —where you cannot put a key—
+    it gets wrapped in `{"data": <response>, "snakeorm": <debug>}`. A non-JSON body is left intact.
+    """
+    try:
+        data = json.loads(body)
+    except (ValueError, UnicodeDecodeError):
+        return body
+    if isinstance(data, dict):
+        data["snakeorm"] = (
+            envelope  # already an object: the key fits as a sibling, no wrapping
+        )
+    else:
+        data = {"data": data, "snakeorm": envelope}  # array/scalar: must be wrapped
+    # `ensure_ascii=False` so the accents do not get re-escaped to `\uXXXX`: it preserves the UTF-8
+    # as it is (the way Starlette does) and does not double the size of a response with non-ASCII
+    # text.
+    return json.dumps(data, ensure_ascii=False).encode()
+
+
+def inject_panel(
+    body: bytes,
+    report: DebugReport,
+    language: SnakeDebugLanguage = SnakeDebugLanguage.EN,
+    csp_nonce: str | None = None,
+    *,
+    token: str | None = None,
+    channels: frozenset[SnakeDebugChannel] | None = None,
+) -> bytes:
+    """Insert the HTML panel right before `</body>`; a body with no such tag comes back INTACT.
+
+    No `</body>` means a FRAGMENT (an HTMX/Alpine swap), and a fragment gets nothing in its body.
+    Appending anything returns two top-level nodes where the application asked for one, which
+    changes `:last-child` under `innerHTML`, adds a child under `outerHTML` and can be dropped by
+    `hx-select`. The fragment's debug travels in the headers instead. `</body>` is the
+    discriminator on purpose: `HX-Request` would tie this to one library.
+
+    `csp_nonce` travels through to the mounting script. An application with a strict
+    Content-Security-Policy generates one per response and hands it in; without it the panel is
+    injected exactly as before, and under `script-src 'self'` the browser drops it in silence.
+    """
+    marker = b"</body>"
+    if marker not in body:
+        return body
+    panel = render_report_html(
+        report,
+        language=language,
+        csp_nonce=csp_nonce,
+        token=token,
+        channels=channels,
+    ).encode()
+    return body.replace(marker, panel + marker, 1)
+
+
+def transform_body(
+    body: bytes,
+    content_type: str,
+    delivery: Delivery,
+    report: DebugReport,
+    channels: frozenset[SnakeDebugChannel],
+    language: SnakeDebugLanguage = SnakeDebugLanguage.EN,
+    csp_nonce: str | None = None,
+    *,
+    token: str | None = None,
+) -> bytes:
+    """Rewrite the body by `Content-Type` (envelope in JSON, panel in HTML): one adapter serves a hybrid app without wiring two things.
+
+    `csp_nonce` and `token` ride alongside `language`: this is the ONLY path the three adapters take
+    to render the panel, so anything that does not travel here never reaches a middleware-delivered
+    page. The channels travel too — the history tab reads them to say `envelope` is missing.
+    """
+    if delivery.envelope is not None and "application/json" in content_type:
+        return inject_envelope(body, delivery.envelope)
+    if SnakeDebugChannel.SSR in channels and "text/html" in content_type:
+        return inject_panel(
+            body, report, language, csp_nonce, token=token, channels=channels
+        )
+    return body