lorebase-keeper 0.2.3__py3-none-any.whl

lorebase_keeper/routes/domains.py

@@ -0,0 +1,220 @@
+"""Domains (design 5.2, 11.1): create, list, read, update display metadata, delete.
+
+Creating a Domain needs the installation-level `domain.create` permission; the creator gets
+the configured role (`keeper.domains.creator_role`, default `admin`) in the new Domain.
+Deleting one needs `domain.delete`, which only the Domain's `admin` role holds, and the Domain
+id repeated in `confirm`: the deletion removes every Revision, branch and grant of the Domain
+and cannot be undone (the audit log keeps its entries).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, Query, Request, Response
+from pydantic import BaseModel, Field, JsonValue
+
+from lorebase_core.canonical import hex
+from lorebase_core.model import Domain
+from lorebase_keeper.auth.audit import annotate
+from lorebase_keeper.auth.deps import (
+    Access,
+    AuthDep,
+    PrincipalDep,
+    limited_kinds,
+    require,
+    require_installation,
+)
+from lorebase_keeper.auth.permissions import Permission
+from lorebase_keeper.context import StoreDep
+from lorebase_keeper.deps import IdempotencyKeyDep, KeeperSettingsDep
+from lorebase_keeper.errors import VALIDATION_FAILED, Problem, ProblemError, ValidationProblem
+from lorebase_keeper.pagination import Page, PageParamsDep, encode_cursor
+from lorebase_keeper.services import domains as service
+from lorebase_keeper.services.branches import check_ref_name
+from lorebase_store.repositories import DomainRow
+
+router = APIRouter(tags=["domains"])
+
+DOMAIN_ID_PATTERN = r"^[a-z][a-z0-9_-]*$"
+REPLAYED_HEADER = "Idempotent-Replayed"
+
+_ERRORS: dict[int | str, dict[str, Any]] = {
+    403: {"model": Problem, "description": "The caller lacks the permission named in the body."},
+    404: {"model": Problem, "description": "Domain not found."},
+    409: {"model": Problem, "description": "The Domain already exists."},
+    422: {"model": ValidationProblem, "description": "Invalid request."},
+}
+
+
+class DomainCreate(BaseModel):
+    """A new Domain."""
+
+    id: str = Field(pattern=DOMAIN_ID_PATTERN, max_length=63, description="Immutable slug.")
+    display_name: str = Field(default="", max_length=200)
+    description: str = Field(default="", max_length=4000)
+    default_branch: str = Field(default="main", min_length=1, max_length=200)
+    settings: dict[str, JsonValue] = Field(
+        default_factory=dict, description="Search language, materialization and merge policies."
+    )
+
+
+class DomainUpdate(BaseModel):
+    """Display metadata; omitted members are left unchanged."""
+
+    display_name: str | None = Field(default=None, min_length=1, max_length=200)
+    description: str | None = Field(default=None, max_length=4000)
+
+
+class DomainOut(BaseModel):
+    """A Domain and the head Revision of its default branch."""
+
+    id: str
+    display_name: str
+    description: str | None
+    default_branch: str
+    settings: dict[str, Any]
+    created_at: datetime
+    created_by: str
+    head: str | None = Field(description="Head Revision of the default branch.")
+
+
+def _out(row: DomainRow, head: bytes | None) -> DomainOut:
+    return DomainOut(
+        id=row.id,
+        display_name=row.display_name,
+        description=row.description,
+        default_branch=row.default_branch,
+        settings=dict(row.settings),
+        created_at=row.created_at,
+        created_by=row.created_by,
+        head=None if head is None else hex(head),
+    )
+
+
+@router.post("/domains", status_code=201, summary="Create a Domain", responses=_ERRORS)
+async def create_domain(
+    body: DomainCreate,
+    request: Request,
+    response: Response,
+    store: StoreDep,
+    keeper: KeeperSettingsDep,
+    auth: AuthDep,
+    idempotency_key: IdempotencyKeyDep,
+    access: Annotated[Access, Depends(require_installation(Permission.DOMAIN_CREATE))],
+) -> DomainOut:
+    """Create a Domain with an initial Revision on its default branch (protected by default).
+
+    With an `Idempotency-Key`, retrying a create that succeeded returns the Domain with
+    status 200 and `Idempotent-Replayed: true`.
+    """
+    check_ref_name(body.default_branch, keeper.branches, "/body/default_branch")
+    domain = Domain(
+        id=body.id,
+        display_name=body.display_name,
+        description=body.description,
+        default_branch=body.default_branch,
+        settings=body.settings,
+    )
+    created = await service.create(
+        store, domain, access.principal, keeper.domains, idempotency_key=idempotency_key
+    )
+    auth.authorizer.invalidate()
+    annotate(request, domain_id=body.id, action="domain.create", target=body.id)
+    if created.replayed:
+        response.status_code = 200
+        response.headers[REPLAYED_HEADER] = "true"
+    response.headers["Location"] = f"{keeper.api_prefix}/domains/{body.id}"
+    return _out(created.domain, created.head)
+
+
+@router.get("/domains", summary="List Domains", responses=_ERRORS)
+async def list_domains(
+    principal: PrincipalDep, auth: AuthDep, store: StoreDep, params: PageParamsDep
+) -> Page[DomainOut]:
+    """Domains whose schema the caller may read (also through grants narrowed to Kinds that
+    are invisible to it otherwise), ordered by id."""
+    after = None if params.position is None else str(params.position.get("id", ""))
+    items: list[DomainOut] = []
+    more = True
+    # Domains the caller cannot see are skipped: read further batches until the page is full.
+    while more and len(items) < params.limit:
+        rows = await service.page(store, limit=params.limit, after=after)
+        more = len(rows) == params.limit
+        for position, row in enumerate(rows):
+            after = row.id
+            if await auth.authorizer.allows(
+                principal, Permission.SCHEMA_READ, row.id
+            ) or await limited_kinds(auth.authorizer, principal, Permission.SCHEMA_READ, row.id):
+                items.append(_out(row, None))
+            if len(items) == params.limit:
+                more = more or position < len(rows) - 1
+                break
+    next_cursor = encode_cursor({"id": after}) if more and after is not None else None
+    return Page[DomainOut](items=items, next_cursor=next_cursor)
+
+
+@router.get("/domains/{domain_id}", summary="Get a Domain", responses=_ERRORS)
+async def get_domain(
+    domain_id: str,
+    store: StoreDep,
+    _: Annotated[Access, Depends(require(Permission.SCHEMA_READ, kind_limited=True))],
+) -> DomainOut:
+    """The Domain and the head Revision of its default branch."""
+    row, head = await service.get(store, domain_id)
+    return _out(row, head)
+
+
+@router.patch("/domains/{domain_id}", summary="Update Domain display metadata", responses=_ERRORS)
+async def update_domain(
+    domain_id: str,
+    body: DomainUpdate,
+    request: Request,
+    store: StoreDep,
+    _: Annotated[Access, Depends(require(Permission.DOMAIN_SETTINGS))],
+) -> DomainOut:
+    """Change the display name or description. They are not versioned."""
+    await service.update(
+        store, domain_id, display_name=body.display_name, description=body.description
+    )
+    annotate(
+        request,
+        action="domain.update",
+        target=domain_id,
+        fields=sorted(body.model_dump(exclude_unset=True)),
+    )
+    row, head = await service.get(store, domain_id)
+    return _out(row, head)
+
+
+@router.delete(
+    "/domains/{domain_id}", status_code=204, summary="Delete a Domain", responses=_ERRORS
+)
+async def delete_domain(
+    domain_id: str,
+    request: Request,
+    store: StoreDep,
+    auth: AuthDep,
+    confirm: Annotated[str, Query(description="The Domain id, repeated to confirm.")],
+    _: Annotated[Access, Depends(require(Permission.DOMAIN_DELETE))],
+) -> Response:
+    """Delete the Domain with all its Revisions, branches, materialized rows and grants."""
+    if confirm != domain_id:
+        raise ProblemError(
+            VALIDATION_FAILED,
+            "One or more request members are invalid.",
+            extensions={
+                "errors": [
+                    {
+                        "pointer": "/query/confirm",
+                        "message": "must repeat the Domain id",
+                        "code": "invalid",
+                    }
+                ]
+            },
+        )
+    await service.delete(store, domain_id)
+    auth.authorizer.invalidate()
+    annotate(request, action="domain.delete", target=domain_id)
+    return Response(status_code=204)

lorebase_keeper/routes/events.py

@@ -0,0 +1,187 @@
+"""Change feed of a branch (`agents.feed`): Server-Sent Events and the polling fallback.
+
+Both are history reads: they need `data.read` on the branch through a grant not narrowed to a
+Kind, like the branch log. An open stream repeats that check (authentication included) every
+`agents.feed.reauthorize_interval_s` and closes when it fails.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, Header, Query, Request, Response
+from fastapi.responses import StreamingResponse
+
+from lorebase_keeper.agents.feed import (
+    EVENT_STREAM,
+    ChangesFeedPage,
+    changes_since,
+    kind_filter,
+    parse_sequence,
+    stream,
+)
+from lorebase_keeper.auth.deps import AuthDep
+from lorebase_keeper.client_address import client_address
+from lorebase_keeper.errors import Problem, ProblemError, ValidationProblem
+from lorebase_keeper.reading.caching import respond
+from lorebase_keeper.reading.points import (
+    REVISION_HEADER,
+    branch_schema,
+    open_branch,
+    open_domain,
+    open_revision,
+    read_guard,
+)
+from lorebase_keeper.reading.problems import invalid
+from lorebase_keeper.reading.runtime import ReadRuntimeDep, ReadSessionDep, begin_read
+from lorebase_keeper.routes.agents import AgentSettingsDep
+from lorebase_keeper.services.reads import ReadGuard
+from lorebase_store.repositories import OutboxRepository
+
+router = APIRouter(tags=["agents"])
+
+BASE = "/domains/{domain_id}"
+_ERRORS: dict[int | str, dict[str, Any]] = {
+    403: {"model": Problem, "description": "The caller lacks data.read for the branch."},
+    404: {"model": Problem, "description": "Domain, branch or Revision not found."},
+    422: {"model": ValidationProblem, "description": "Invalid request."},
+}
+
+DataRead = Annotated[ReadGuard, Depends(read_guard())]
+Kinds = Annotated[
+    list[str] | None,
+    Query(description="Only events changing these Kinds (repeated or comma-separated)."),
+]
+
+
+@router.get(
+    f"{BASE}/branches/{{branch:path}}/events",
+    summary="Stream the Revisions of a branch (Server-Sent Events)",
+    response_class=StreamingResponse,
+    responses={
+        **_ERRORS,
+        200: {
+            "content": {EVENT_STREAM: {}},
+            "description": "`event: revision` messages whose `data` is a RevisionEventOut and "
+            "whose `id` is the event sequence; comment lines as heartbeats.",
+        },
+    },
+)
+async def branch_events(
+    domain_id: str,
+    branch: str,
+    access: DataRead,
+    runtime: ReadRuntimeDep,
+    settings: AgentSettingsDep,
+    auth: AuthDep,
+    request: Request,
+    kinds: Kinds = None,
+    last_event_id: Annotated[
+        str | None,
+        Query(description="Resume after this event id (for clients that cannot set headers)."),
+    ] = None,
+    last_event_header: Annotated[str | None, Header(alias="Last-Event-ID")] = None,
+) -> StreamingResponse:
+    """Revisions committed on the branch from now on, or after `Last-Event-ID`."""
+    async with runtime.sessions() as session, session.begin():
+        await begin_read(session, runtime)
+        domain = await open_domain(session, access)
+        ref = await open_branch(session, access, domain, branch)
+        wanted = kind_filter(await branch_schema(session, runtime, domain.id, ref.name), kinds)
+        start = parse_sequence(last_event_header or last_event_id)
+        if start is None:
+            start = await OutboxRepository(session).latest(domain.id)
+
+    async def still_allowed() -> bool:
+        """The checks above, again: the credential (revoked or expired keys and tokens, the
+        networks of a key), then `data.read` on the branch. Grants come through the
+        authorizer's cache."""
+        try:
+            principal = await auth.authenticator.authenticate(
+                request.headers, client_address(request)
+            )
+            guard = replace(access, principal=principal)
+            await guard.precheck()
+            await guard.require_branch(ref.name)
+        except ProblemError:
+            return False
+        return True
+
+    return StreamingResponse(
+        stream(
+            runtime,
+            domain.id,
+            ref.name,
+            start,
+            wanted,
+            settings.feed,
+            request.is_disconnected,
+            still_allowed,
+        ),
+        media_type=EVENT_STREAM,
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+            REVISION_HEADER: ref.head.hex(),
+        },
+    )
+
+
+@router.get(
+    f"{BASE}/branches/{{branch:path}}/changes",
+    summary="Revisions of a branch since a Revision",
+    response_model=ChangesFeedPage,
+    responses={
+        **_ERRORS,
+        304: {"description": "Not modified: If-None-Match names the current ETag."},
+        409: {"model": Problem, "description": "`since` is not reachable from the head."},
+    },
+)
+async def branch_changes(
+    domain_id: str,
+    branch: str,
+    access: DataRead,
+    runtime: ReadRuntimeDep,
+    session: ReadSessionDep,
+    settings: AgentSettingsDep,
+    request: Request,
+    since: Annotated[
+        str | None,
+        Query(description="Revision id or tag; default: the latest Revisions."),
+    ] = None,
+    kinds: Kinds = None,
+    limit: Annotated[int | None, Query(ge=1, description="Page size.")] = None,
+) -> Response:
+    """First-parent Revisions after `since`, oldest first; continue with `next_since`."""
+    domain = await open_domain(session, access)
+    ref = await open_branch(session, access, domain, branch)
+    bounds = settings.feed.changes
+    effective = bounds.default_limit if limit is None else limit
+    if effective > bounds.max_limit:
+        raise invalid("/query/limit", f"must not exceed {bounds.max_limit}", "limit_exceeded")
+    since_row = None if since is None else await open_revision(session, access, domain, since)
+    wanted = kind_filter(await branch_schema(session, runtime, domain.id, ref.name), kinds)
+
+    async def produce() -> ChangesFeedPage:
+        return await changes_since(
+            session,
+            runtime,
+            domain.id,
+            ref.name,
+            ref.head,
+            since_row,
+            limit=effective,
+            wanted=wanted,
+            settings=settings.feed,
+        )
+
+    return await respond(
+        request,
+        runtime.cache,
+        domain_id=domain.id,
+        revision=ref.head.hex(),
+        produce=produce,
+        headers={REVISION_HEADER: ref.head.hex()},
+        variant="" if since_row is None else since_row.id.hex(),
+    )

lorebase_keeper/routes/kind_health.py

@@ -0,0 +1,166 @@
+"""Health reports (design 14): how sound the data of a Domain, or of one Kind, is.
+
+Computed on request from the materialized head of a branch, or with `at` from a snapshot of an
+earlier Revision (`reading.snapshots`), and kept in the response cache under the Revision they
+describe, so asking again costs nothing until the branch moves. Callers with
+Kind-narrowed grants get a report limited to those Kinds. `format=markdown` renders the report
+for pasting into a prompt.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from fastapi import APIRouter, Depends, Query, Request, Response
+
+from lorebase_keeper.agents.context import JSON, MARKDOWN
+from lorebase_keeper.errors import Problem, ValidationProblem
+from lorebase_keeper.kindhealth import markdown, report
+from lorebase_keeper.kindhealth.models import DomainHealthOut, KindHealthOut
+from lorebase_keeper.reading.caching import cache_key, respond_with
+from lorebase_keeper.reading.points import REVISION_HEADER, read_guard, resolve_point
+from lorebase_keeper.reading.records import require_kind
+from lorebase_keeper.reading.runtime import ReadRuntimeDep, ReadSessionDep
+from lorebase_keeper.reading.snapshots import with_rows
+from lorebase_keeper.reading.views import served
+from lorebase_keeper.services.reads import ReadGuard
+
+router = APIRouter(tags=["health"])
+
+BASE = "/domains/{domain_id}"
+_ERRORS: dict[int | str, dict[str, Any]] = {
+    403: {"model": Problem, "description": "The caller lacks data.read for the branch."},
+    404: {"model": Problem, "description": "Domain, branch or Kind not found."},
+    422: {"model": ValidationProblem, "description": "Invalid request."},
+    503: {"model": Problem, "description": "The scan exceeded its statement timeout."},
+}
+
+DataRead = Annotated[ReadGuard, Depends(read_guard())]
+Branch = Annotated[
+    str | None, Query(description="Branch to examine; default: the Domain's default branch.")
+]
+At = Annotated[
+    str | None,
+    Query(description="Revision id or tag to examine (time travel, served from a snapshot)."),
+]
+Format = Annotated[
+    Literal["json", "markdown"], Query(description="`markdown` renders the report as text.")
+]
+
+
+@router.get(
+    f"{BASE}/health",
+    summary="Health of a Domain",
+    responses={
+        **_ERRORS,
+        200: {
+            "model": DomainHealthOut,
+            "content": {JSON: {}, MARKDOWN: {}},
+            "description": "The report in JSON, or markdown with `format=markdown`.",
+        },
+        304: {"description": "Not modified: If-None-Match names the current ETag."},
+    },
+)
+async def domain_health(
+    domain_id: str,
+    access: DataRead,
+    runtime: ReadRuntimeDep,
+    session: ReadSessionDep,
+    request: Request,
+    branch: Branch = None,
+    at: At = None,
+    format: Format = "json",
+) -> Response:
+    """Per Kind: Records, Links by Relation, constraint violations against the current schema,
+    required-relation gaps, orphan Links, duplicates on unique and title Attributes, stale
+    derived values and the last change; for the Kinds the caller may read."""
+    point = await resolve_point(session, runtime, access, branch=branch, at=at)
+
+    async def produce() -> tuple[bytes, str]:
+        rows = await with_rows(session, runtime, point, "Health reports")
+        found = await report.scan_branch(
+            session,
+            rows,
+            runtime.read.health,
+            report.visible_kinds(point),
+            report.visible_relations(point),
+        )
+        out = DomainHealthOut(
+            **served(point),
+            domain=point.domain.id,
+            branch=point.branch,
+            summary=found.summary,
+            kinds=found.kinds,
+            relations=found.relations,
+        )
+        if format == "markdown":
+            return markdown.domain_markdown(out).encode(), MARKDOWN
+        return out.model_dump_json().encode(), JSON
+
+    return await respond_with(
+        request,
+        runtime.cache,
+        cache_key(request, point.domain.id, point.revision_hex, point.variant),
+        produce,
+        time_travel=not point.materialized,
+        headers={REVISION_HEADER: point.revision_hex},
+    )
+
+
+@router.get(
+    f"{BASE}/kinds/{{kind}}/health",
+    summary="Health of a Kind",
+    responses={
+        **_ERRORS,
+        200: {
+            "model": KindHealthOut,
+            "content": {JSON: {}, MARKDOWN: {}},
+            "description": "The report in JSON, or markdown with `format=markdown`.",
+        },
+        304: {"description": "Not modified: If-None-Match names the current ETag."},
+    },
+)
+async def kind_health(
+    domain_id: str,
+    kind: str,
+    access: DataRead,
+    runtime: ReadRuntimeDep,
+    session: ReadSessionDep,
+    request: Request,
+    branch: Branch = None,
+    at: At = None,
+    format: Format = "json",
+) -> Response:
+    """The checks of the Domain report for one Kind, with the Relations it takes part in."""
+    point = await resolve_point(session, runtime, access, branch=branch, at=at)
+    found_kind = require_kind(point, kind)
+
+    async def produce() -> tuple[bytes, str]:
+        rows = await with_rows(session, runtime, point, "Health reports")
+        found = await report.scan_branch(
+            session,
+            rows,
+            runtime.read.health,
+            [found_kind],
+            report.visible_relations(point, found_kind),
+        )
+        out = KindHealthOut(
+            **served(point),
+            domain=point.domain.id,
+            branch=point.branch,
+            summary=found.summary,
+            health=found.kinds[0],
+            relations=report.with_direction(found.relations, found_kind),
+        )
+        if format == "markdown":
+            return markdown.kind_markdown(out).encode(), MARKDOWN
+        return out.model_dump_json().encode(), JSON
+
+    return await respond_with(
+        request,
+        runtime.cache,
+        cache_key(request, point.domain.id, point.revision_hex, point.variant),
+        produce,
+        time_travel=not point.materialized,
+        headers={REVISION_HEADER: point.revision_hex},
+    )