queryview 0.0.2__py3-none-any.whl

queryview/test_workspaces.py

@@ -0,0 +1,109 @@
+"""Workspace store: CRUD, name rules, encrypted-remote round trip, and the
+delete-refuses-on-non-empty rule. The 'default' workspace is seeded by the
+migration and is an ordinary row."""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+
+import pytest
+
+from queryview.connect import _db_path
+from queryview.workspaces import (
+    DEFAULT_WORKSPACE,
+    WorkspaceError,
+    create_workspace,
+    delete_workspace,
+    list_workspaces,
+    resolve,
+    update_workspace,
+)
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+def test_default_workspace_is_seeded():
+    rec = _run(resolve(DEFAULT_WORKSPACE))
+    assert rec.name == "default"
+    assert isinstance(rec.id, int)
+
+
+def test_resolve_unknown_is_404():
+    with pytest.raises(WorkspaceError) as e:
+        _run(resolve("no-such-ws"))
+    assert e.value.status == 404
+
+
+def test_create_list_and_encrypted_remote_round_trip():
+    _run(create_workspace("t2-crt", remote="https://u:tok@example.test/r.git", branch="dev"))
+    rec = _run(resolve("t2-crt"))
+    assert rec.remote == "https://u:tok@example.test/r.git"  # decrypted for gitsync
+    assert rec.branch == "dev"
+
+    listed = {w["name"]: w for w in _run(list_workspaces())}
+    assert listed["t2-crt"] == {"name": "t2-crt", "branch": "dev", "configured": True}
+    assert "remote" not in listed["t2-crt"]  # the URL (a secret) never leaves the store
+
+    # At rest the remote is ciphertext, not the URL.
+    con = sqlite3.connect(_db_path())
+    try:
+        stored = con.execute("SELECT remote FROM workspaces WHERE name='t2-crt'").fetchone()[0]
+    finally:
+        con.close()
+    assert "example.test" not in stored
+
+
+def test_create_duplicate_is_409_and_bad_names_400():
+    _run(create_workspace("t2-dup"))
+    with pytest.raises(WorkspaceError) as e:
+        _run(create_workspace("t2-dup"))
+    assert e.value.status == 409
+    with pytest.raises(WorkspaceError) as e:
+        _run(create_workspace("   "))
+    assert e.value.status == 400
+    with pytest.raises(WorkspaceError) as e:
+        _run(create_workspace("a/b"))  # names travel in URL paths
+    assert e.value.status == 400
+
+
+def test_update_rename_set_and_clear_remote():
+    _run(create_workspace("t2-upd", remote="https://example.test/a.git"))
+    _run(update_workspace("t2-upd", new_name="t2-upd2", branch="rel"))
+    rec = _run(resolve("t2-upd2"))
+    assert rec.branch == "rel" and rec.remote == "https://example.test/a.git"  # remote untouched
+    _run(update_workspace("t2-upd2", remote=None))
+    assert _run(resolve("t2-upd2")).remote is None
+    with pytest.raises(WorkspaceError) as e:
+        _run(update_workspace("t2-upd2", new_name=DEFAULT_WORKSPACE))
+    assert e.value.status == 409
+
+
+def test_delete_refuses_non_empty_then_deletes_empty():
+    _run(create_workspace("t2-del"))
+    rec = _run(resolve("t2-del"))
+    con = sqlite3.connect(_db_path())
+    try:
+        con.execute(
+            "INSERT INTO predefined_queries (query_name, type, query, workspace_id) "
+            "VALUES ('held', 'clickhouse', 'SELECT 1', ?)",
+            (rec.id,),
+        )
+        con.commit()
+    finally:
+        con.close()
+    with pytest.raises(WorkspaceError) as e:
+        _run(delete_workspace("t2-del"))
+    assert e.value.status == 409
+
+    con = sqlite3.connect(_db_path())
+    try:
+        con.execute("DELETE FROM predefined_queries WHERE workspace_id=?", (rec.id,))
+        con.commit()
+    finally:
+        con.close()
+    _run(delete_workspace("t2-del"))
+    with pytest.raises(WorkspaceError):
+        _run(resolve("t2-del"))

queryview/test_yamlio.py

@@ -0,0 +1,198 @@
+"""yamlio: export/import round trips at the module level, plus document
+validation (parse_document rejects malformed files before anything writes)."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+import yaml
+
+from queryview.yamlio import (
+    YamlIOError,
+    export_dashboard,
+    export_query,
+    export_workspace,
+    import_text,
+    parse_document,
+    slug,
+)
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+def test_slug_passthrough_and_encoding():
+    assert slug("top_errors") == "top_errors"
+    assert slug("top errors 2.0") == "top errors 2.0"
+    assert slug("a/b") == "a%2Fb"
+    assert slug(".hidden") == "%2Ehidden"
+    assert slug("héllo") == "h%C3%A9llo"
+
+
+# --- parse_document validation ---------------------------------------------
+
+
+def test_parse_rejects_non_mapping_and_unknown_kind():
+    with pytest.raises(YamlIOError):
+        parse_document("- just\n- a list\n")
+    with pytest.raises(YamlIOError):
+        parse_document("kind: nope\n")
+    with pytest.raises(YamlIOError):
+        parse_document("query_name: no kind\n")
+
+
+def test_parse_rejects_invalid_yaml():
+    with pytest.raises(YamlIOError):
+        parse_document("kind: [unclosed\n")
+
+
+def test_parse_query_requires_fields():
+    with pytest.raises(YamlIOError):
+        parse_document("kind: query\nquery_name: x\n")  # no type/query
+    with pytest.raises(YamlIOError):
+        parse_document("kind: query\ntype: clickhouse\nquery_name: ''\nquery: SELECT 1\n")
+
+
+def test_parse_query_validates_presentation():
+    doc = "kind: query\ntype: clickhouse\nquery_name: x\nquery: SELECT 1\norder_by: notalist\n"
+    with pytest.raises(YamlIOError):
+        parse_document(doc)
+
+
+def test_parse_query_validates_cell_view_yaml():
+    doc = 'kind: query\ntype: clickhouse\nquery_name: x\nquery: SELECT 1\ncell_view: "col: [unclosed"\n'
+    with pytest.raises(YamlIOError):
+        parse_document(doc)
+
+
+def test_parse_dashboard_requires_fields():
+    with pytest.raises(YamlIOError):
+        parse_document("kind: dashboard\nname: d\nconnection: c\n")  # no html
+    with pytest.raises(YamlIOError):
+        parse_document("kind: dashboard\nname: d\nconnection: c\nhtml: <p/>\nqueries: [notamap]\n")
+
+
+def test_parse_workspace_validates_entries():
+    doc = "kind: workspace\nqueries:\n  - query_name: missing type\n    query: SELECT 1\n"
+    with pytest.raises(YamlIOError):
+        parse_document(doc)
+    with pytest.raises(YamlIOError):
+        parse_document("kind: workspace\nqueries: notalist\n")
+
+
+def test_parse_empty_workspace_bundle_is_valid():
+    kind, payload = parse_document("kind: workspace\n")
+    assert kind == "workspace"
+    assert payload == {"queries": [], "dashboards": []}
+
+
+# --- Round trips ------------------------------------------------------------
+
+
+def test_query_export_import_round_trip(default_ws_id):
+    from queryview.queries import get_predefined_query, save_predefined_query
+
+    _run(
+        save_predefined_query(
+            "yio query",
+            "clickhouse",
+            "SELECT 1\nFROM t",
+            "col:\n  type: link\n  value: https://x/{cell}\n",
+            '[{"name": "col", "dir": "DESC"}]',
+            '["col"]',
+            workspace_id=default_ws_id,
+        )
+    )
+    text = _run(export_query("clickhouse", "yio query", default_ws_id))
+    data = yaml.safe_load(text)
+    assert data["kind"] == "query" and data["type"] == "clickhouse"
+    assert data["query"] == "SELECT 1\nFROM t"
+
+    # Re-import under a changed name to prove the import writes the file's
+    # content, then compare rows field by field.
+    _run(import_text(text.replace("yio query", "yio query copy"), default_ws_id))
+    orig = _run(get_predefined_query("clickhouse", "yio query", default_ws_id))
+    copy = _run(get_predefined_query("clickhouse", "yio query copy", default_ws_id))
+    assert orig is not None and copy is not None
+    for key in ("query", "cell_view", "fields"):
+        assert copy[key] == orig[key]
+    import json
+
+    ob_copy, ob_orig = copy["order_by"], orig["order_by"]
+    assert ob_copy is not None and ob_orig is not None
+    assert json.loads(ob_copy) == json.loads(ob_orig)
+
+
+def test_dashboard_export_import_round_trip(default_ws_id):
+    from queryview.dashboards import get_dashboard, upsert_dashboard
+
+    _run(
+        upsert_dashboard(
+            "yio dash",
+            "prod",
+            "<html>\n<body>v1</body>\n</html>",
+            {"panel": "SELECT 1"},
+            workspace_id=default_ws_id,
+        )
+    )
+    text = _run(export_dashboard("yio dash", default_ws_id))
+    data = yaml.safe_load(text)
+    assert data["kind"] == "dashboard" and data["connection"] == "prod"
+
+    # Drift the stored copy, then import the export to restore it.
+    _run(upsert_dashboard("yio dash", "other", "<p>v2</p>", {}, workspace_id=default_ws_id))
+    r = _run(import_text(text, default_ws_id))
+    assert r == {"kind": "dashboard", "queries": 0, "dashboards": 1}
+    d = _run(get_dashboard("yio dash", default_ws_id))
+    assert d is not None
+    assert d["connection"] == "prod" and "v1" in d["html"] and d["queries"] == {"panel": "SELECT 1"}
+
+
+def test_workspace_export_import_round_trip(default_ws_id, wipe_workspace_entities):
+    """Export one workspace's whole content and import it into another."""
+    from queryview.dashboards import get_dashboard, upsert_dashboard
+    from queryview.queries import get_predefined_query, save_predefined_query
+    from queryview.workspaces import create_workspace, delete_workspace, resolve
+
+    _run(save_predefined_query("ws q1", "clickhouse", "SELECT 1", workspace_id=default_ws_id))
+    _run(save_predefined_query("ws q2", "postgres", "SELECT 2", workspace_id=default_ws_id))
+    _run(upsert_dashboard("ws dash", "prod", "<p>hi</p>", {"a": "SELECT 3"}, workspace_id=default_ws_id))
+    text = _run(export_workspace(default_ws_id))
+    data = yaml.safe_load(text)
+    assert data["kind"] == "workspace"
+    names = {(q["type"], q["query_name"]) for q in data["queries"]}
+    assert {("clickhouse", "ws q1"), ("postgres", "ws q2")} <= names
+
+    _run(create_workspace("yio target"))
+    try:
+        target = _run(resolve("yio target"))
+        r = _run(import_text(text, target.id))
+        assert r["kind"] == "workspace" and r["queries"] >= 2 and r["dashboards"] >= 1
+        q = _run(get_predefined_query("postgres", "ws q2", target.id))
+        assert q is not None and q["query"] == "SELECT 2"
+        d = _run(get_dashboard("ws dash", target.id))
+        assert d is not None and d["queries"] == {"a": "SELECT 3"}
+        # Clean the target so delete_workspace succeeds (it must be empty).
+        wipe_workspace_entities(target.id)
+    finally:
+        _run(delete_workspace("yio target"))
+
+
+def test_import_validates_before_writing(default_ws_id):
+    """A workspace bundle with one bad entry writes nothing at all."""
+    from queryview.queries import get_predefined_query
+
+    doc = (
+        "kind: workspace\n"
+        "queries:\n"
+        "  - type: clickhouse\n"
+        "    query_name: good entry\n"
+        "    query: SELECT 1\n"
+        "  - type: clickhouse\n"
+        "    query_name: bad entry\n"
+    )
+    with pytest.raises(YamlIOError):
+        _run(import_text(doc, default_ws_id))
+    assert _run(get_predefined_query("clickhouse", "good entry", default_ws_id)) is None

queryview/validation.py

@@ -0,0 +1,111 @@
+"""Strict validation for the presentation fields carried on a push, a
+predefined-query save, or a YAML import/restore: order_by/fields (structured)
+and cell_view (raw YAML text, checked against the contract in
+docs/query.md#cell-views). Shared by every write path so they all enforce the
+same rules; reads stay lenient (the client drops entries it can't use)."""
+
+from __future__ import annotations
+
+import yaml
+
+MAX_LIMIT = 10000
+
+
+def presentation_error(order_by: object, fields: object) -> str | None:
+    """Return an error message if order_by/fields are malformed, else None.
+    None inputs are valid (the field is simply absent/unchanged)."""
+    if order_by is not None:
+        if not isinstance(order_by, list):
+            return "invalid order_by: must be a list"
+        for col in order_by:
+            if not isinstance(col, dict):
+                return "invalid order_by: each entry must be an object"
+            name = col.get("name")
+            if not isinstance(name, str) or not name:
+                return "invalid order_by: name must be a non-empty string"
+            if "`" in name:
+                return "invalid order_by: name must not contain a backtick"
+            direction = col.get("dir")
+            if not isinstance(direction, str) or direction.upper() not in ("ASC", "DESC"):
+                return "invalid order_by: dir must be ASC or DESC"
+    if fields is not None:
+        if not isinstance(fields, list):
+            return "invalid fields: must be a list"
+        for f in fields:
+            if not isinstance(f, str) or not f:
+                return "invalid fields: each column must be a non-empty string"
+    return None
+
+
+def _cell_view_params_error(raw: object) -> str | None:
+    """Validate the reserved `params:` selector list (see docs/query.md)."""
+    if not isinstance(raw, list):
+        return "invalid cell_view: params must be a list of selector specs"
+    for i, entry in enumerate(raw):
+        if not isinstance(entry, dict):
+            return f"invalid cell_view: params[{i}] must be a mapping"
+        name = entry.get("name")
+        if not isinstance(name, str) or not name:
+            return f"invalid cell_view: params[{i}] name must be a non-empty string"
+        options, sql = entry.get("options"), entry.get("options_sql")
+        if (options is None) == (sql is None):
+            return f"invalid cell_view: params[{i}] must declare exactly one of options or options_sql"
+        if sql is not None and (not isinstance(sql, str) or not sql.strip()):
+            return f"invalid cell_view: params[{i}] options_sql must be a non-empty string"
+        if options is not None:
+            if not isinstance(options, list) or not options:
+                return f"invalid cell_view: params[{i}] options must be a non-empty list"
+            if any(isinstance(v, (dict, list)) or v is None for v in options):
+                return f"invalid cell_view: params[{i}] options must be scalars"
+    return None
+
+
+def cell_view_error(cell_view: object) -> str | None:
+    """Return an error message if a cell_view YAML text is malformed, else None.
+    None / empty text is valid (no custom views). The contract
+    (docs/query.md#cell-views): a YAML mapping whose reserved `params` key holds
+    selector specs and whose other entries are column -> {type: link|custom,
+    value: str} (extra keys are allowed)."""
+    if cell_view is None:
+        return None
+    if not isinstance(cell_view, str):
+        return "invalid cell_view: must be YAML text"
+    if not cell_view.strip():
+        return None
+    try:
+        doc = yaml.safe_load(cell_view)
+    except yaml.YAMLError as e:
+        return f"invalid cell_view: not valid YAML ({e})"
+    if doc is None:
+        return None
+    if not isinstance(doc, dict):
+        return "invalid cell_view: must be a YAML mapping of column -> {type, value}"
+    for key, entry in doc.items():
+        if not isinstance(key, str) or not key:
+            return "invalid cell_view: column names must be non-empty strings"
+        if key == "params":
+            perr = _cell_view_params_error(entry)
+            if perr is not None:
+                return perr
+            continue
+        if not isinstance(entry, dict):
+            return f"invalid cell_view: entry {key!r} must be a {{type, value}} mapping"
+        if entry.get("type") not in ("link", "custom"):
+            return f"invalid cell_view: entry {key!r} type must be 'link' or 'custom'"
+        value = entry.get("value")
+        if not isinstance(value, str) or not value:
+            return f"invalid cell_view: entry {key!r} value must be a non-empty string"
+    return None
+
+
+def clamp_paging(limit: object, offset: object) -> tuple[int, int]:
+    """Coerce/clamp limit & offset to safe ints: 0 <= limit <= MAX_LIMIT, offset >= 0."""
+    try:
+        lim = int(limit)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        lim = 100
+    try:
+        off = int(offset)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        off = 0
+    return max(0, min(lim, MAX_LIMIT)), max(0, off)

queryview/workspaces.py

@@ -0,0 +1,167 @@
+"""Workspace domain: named git-sync targets that own predefined queries and
+dashboards. The remote URL may embed a token, so it is encrypted at rest with
+connect.py's AES-GCM helpers and never returned by list_workspaces. Docs:
+docs/workspace.md."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from sqlalchemy import text
+from sqlmodel import Field, SQLModel, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from .connect import _decrypt_str, _encrypt_str, _engine_for_db, _ensure_schema
+
+DEFAULT_WORKSPACE = "default"
+
+
+class WorkspaceError(Exception):
+    """Workspace failure carrying an HTTP-ish status for the API layer:
+    400 invalid input, 404 unknown workspace, 409 conflict (duplicate name,
+    delete of a non-empty workspace)."""
+
+    def __init__(self, message: str, status: int = 400):
+        super().__init__(message)
+        self.status = status
+
+
+class Workspace(SQLModel, table=True):
+    __tablename__: ClassVar[str] = "workspaces"
+
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(unique=True, index=True)
+    remote: str | None = Field(default=None)  # base64(AES-GCM(url)) — never plaintext
+    branch: str = Field(default="main")
+
+
+@dataclass
+class WorkspaceRec:
+    """A resolved workspace with its remote decrypted, ready for gitsync."""
+
+    id: int
+    name: str
+    remote: str | None
+    branch: str
+
+
+def _to_rec(row: Workspace) -> WorkspaceRec:
+    return WorkspaceRec(
+        id=row.id,  # type: ignore[arg-type]  # persisted rows always have an id
+        name=row.name,
+        remote=_decrypt_str(row.remote) if row.remote else None,
+        branch=row.branch,
+    )
+
+
+def _valid_name(name: str) -> str:
+    name = name.strip()
+    if not name:
+        raise WorkspaceError("workspace name is required", status=400)
+    if "/" in name:
+        # Names travel in /api/workspaces/{name} URL paths.
+        raise WorkspaceError("workspace name must not contain '/'", status=400)
+    return name
+
+
+async def resolve(name: str) -> WorkspaceRec:
+    """The named workspace, or 404. Every workspace-scoped operation starts here."""
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        row = (await s.exec(select(Workspace).where(Workspace.name == name))).first()
+    if row is None:
+        raise WorkspaceError(f"unknown workspace {name!r}", status=404)
+    return _to_rec(row)
+
+
+async def list_workspaces() -> list[dict[str, Any]]:
+    """All workspaces ordered by name; exposes whether a remote is configured
+    but never the remote itself."""
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        rows = (await s.exec(select(Workspace).order_by(Workspace.name))).all()
+    return [{"name": r.name, "branch": r.branch, "configured": bool(r.remote)} for r in rows]
+
+
+async def create_workspace(name: str, remote: str | None = None, branch: str = "main") -> None:
+    name = _valid_name(name)
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        dup = (await s.exec(select(Workspace).where(Workspace.name == name))).first()
+        if dup is not None:
+            raise WorkspaceError(f"workspace {name!r} already exists", status=409)
+        s.add(
+            Workspace(
+                name=name,
+                remote=_encrypt_str(remote) if remote else None,
+                branch=branch.strip() or "main",
+            )
+        )
+        await s.commit()
+
+
+# Sentinel distinguishing "leave the remote as-is" (omitted) from "clear it"
+# (an explicit None).
+_UNSET: Any = object()
+
+
+async def update_workspace(
+    name: str,
+    new_name: str | None = None,
+    remote: Any = _UNSET,
+    branch: str | None = None,
+) -> None:
+    """Rename and/or reconfigure a workspace. Renaming is a one-row update:
+    entities and clone dirs are keyed by workspace id, so nothing else moves."""
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        row = (await s.exec(select(Workspace).where(Workspace.name == name))).first()
+        if row is None:
+            raise WorkspaceError(f"unknown workspace {name!r}", status=404)
+        if new_name is not None and new_name.strip() != name:
+            new_name = _valid_name(new_name)
+            dup = (await s.exec(select(Workspace).where(Workspace.name == new_name))).first()
+            if dup is not None:
+                raise WorkspaceError(f"workspace {new_name!r} already exists", status=409)
+            row.name = new_name
+        if remote is not _UNSET:
+            row.remote = _encrypt_str(remote) if remote else None
+        if branch is not None and branch.strip():
+            row.branch = branch.strip()
+        s.add(row)
+        await s.commit()
+
+
+async def _entity_count(workspace_id: int) -> int:
+    """How many entities the workspace still owns. Raw SQL so this module
+    doesn't import the entity modules (which import nothing from here either)."""
+    async with _engine_for_db().connect() as conn:
+        n = (
+            await conn.execute(
+                text(
+                    "SELECT (SELECT COUNT(*) FROM predefined_queries WHERE workspace_id = :w)"
+                    " + (SELECT COUNT(*) FROM dashboards WHERE workspace_id = :w)"
+                ),
+                {"w": workspace_id},
+            )
+        ).scalar()
+    return int(n or 0)
+
+
+async def delete_workspace(name: str) -> None:
+    """Delete an empty workspace; 409 while it still owns entities. The git
+    remote keeps its history either way — this only removes the local row."""
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        row = (await s.exec(select(Workspace).where(Workspace.name == name))).first()
+        if row is None:
+            raise WorkspaceError(f"unknown workspace {name!r}", status=404)
+        count = await _entity_count(row.id)  # type: ignore[arg-type]
+        if count:
+            raise WorkspaceError(
+                f"workspace {name!r} still contains {count} entities; delete them first",
+                status=409,
+            )
+        await s.delete(row)
+        await s.commit()