Files
tsumugu/backend/app/api/sources.py
T
LarsandClaude Sonnet 5.5 eb58dce4cd
Deploy Development / deploy (push) Successful in 40s
Test Suite / pytest-backend (push) Successful in 3m12s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 21s
Führe die Konfigurationsansicht der Connectoren ein, damit Paperless und IMAP ihre Felder selbst deklarieren.
Das Modul liefert ein Feldmanifest und validiert es; ein leeres Geheimnisfeld behält das gespeicherte. Die Oberfläche rendert die Felder generisch in einer Detailansicht je Zugang mit Prüfstand, Fähigkeiten und Verwendung. Die providerspezifischen Formulare in Sources.jsx entfallen, die flachen API-Felder bleiben als Kompatibilität. Das Standardfach eines IMAP-Kontos öffnet der Picker zuerst.

Die Backend-Tests wurden in der Entwicklungsumgebung nicht ausgeführt; der Lauf auf develop steht aus.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 09:34:37 +02:00

498 lines
17 KiB
Python

"""Connector administration and live Paperless / IMAP lookup."""
from __future__ import annotations
from uuid import UUID
from fastapi import APIRouter, Depends
from fastapi.responses import JSONResponse, Response
from psycopg import Connection
from app.access.policy import Ctx, element_rights, get_element, parse_query_context
from app.api.deps import Principal, get_conn, get_principal
from app.api.routes import _created, _ctx_model
from app.api.schemas import ConnectorIn, ExternalIn, SourceAssignmentIn
from app.core.errors import not_found, unprocessable, unsupported
from app.mailpack import parse_mail
from app.media.storage import content_disposition
from app.ops import create_external
from app.retrieval import RetrievalFailure
from app.sourcebind import assign_reference
from app.sourceport import capability_payload, with_capabilities
from app.sourceregistry import get_source, require_source
from app.sources import (
connector_detail,
delete_connector,
imap_preview,
list_connectors,
owned_connector,
paperless_content,
parse_connector,
probe,
save_connector,
update_connector,
)
_PRIVATE = {
"Cache-Control": "private, no-store",
"Referrer-Policy": "no-referrer",
"X-Content-Type-Options": "nosniff",
}
router = APIRouter()
@router.get("/api/v1/connectors")
def get_connectors(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
return {"items": list_connectors(conn, principal.account_id)}
@router.get("/api/v1/sources/capabilities")
def source_capabilities(principal: Principal = Depends(get_principal)):
del principal
return capability_payload()
@router.post("/api/v1/connectors", status_code=201)
def post_connector(body: ConnectorIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
name, settings, secret = _connector_parts(body, None)
row = save_connector(conn, principal.account_id, body.kind, name, settings, secret)
return row
@router.get("/api/v1/connectors/{connector_id}")
def get_connector(connector_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
return connector_detail(conn, principal.account_id, connector_id)
@router.patch("/api/v1/connectors/{connector_id}")
def patch_connector(
connector_id: UUID,
body: ConnectorIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
current = owned_connector(conn, principal.account_id, connector_id)
if current["kind"] != body.kind:
raise unprocessable("Der Zugang bleibt bei seiner Quellenart.")
name, settings, secret = _connector_parts(body, current)
return update_connector(conn, principal.account_id, connector_id, name, settings, secret)
@router.delete("/api/v1/connectors/{connector_id}", status_code=204)
def remove_connector(connector_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
delete_connector(conn, principal.account_id, connector_id)
@router.post("/api/v1/connectors/{connector_id}/probe")
def probe_connector(connector_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
return probe(conn, principal.account_id, connector_id)
@router.get("/api/v1/external-refs/{element_id}/content")
def view_external_content(
element_id: UUID,
context_kind: str | None = None,
context_id: str | None = None,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
element, context, ref = _opened_ref(conn, principal, element_id, context_kind, context_id)
module = get_source(ref["source"]) if ref is not None else None
if module is None or module.open_original is None:
raise unprocessable("Für diese Quelle ist kein Dateiabruf vorgesehen.")
data, media_type, filename = module.open_original(conn, principal.account_id, element, context, ref)
safe_name = (filename or "dokument.pdf").replace('"', "")
return Response(
content=data,
media_type=media_type,
headers={
**_PRIVATE,
"Content-Disposition": f'inline; filename="{safe_name}"',
},
)
@router.get("/api/v1/external-refs/{element_id}/mail")
def view_mail(
element_id: UUID,
context_kind: str | None = None,
context_id: str | None = None,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
element, context, ref = _opened_ref(conn, principal, element_id, context_kind, context_id)
parsed, _raw = _complete_mail(conn, principal, element, context, ref)
return JSONResponse(
content={
"title": parsed.subject,
"message_from": parsed.sender,
"message_to": parsed.recipient,
"message_cc": parsed.copy,
"text": parsed.text,
"html": parsed.html,
"text_truncated": parsed.text_truncated,
"complete": not parsed.missing,
"notices": parsed.notices,
"attachments": [
{
"index": index,
"filename": item.display_name or item.filename,
"archive_name": item.filename,
"content_type": item.media_type,
"byte_size": len(item.data),
"inline": item.inline,
}
for index, item in enumerate(parsed.attachments)
],
},
headers={"Cache-Control": "private, no-store", "Referrer-Policy": "no-referrer"},
)
def _opened_ref(conn, principal: Principal, element_id: UUID, context_kind: str | None, context_id: str | None):
element = get_element(conn, element_id)
if element is None or element["kind"] != "external_ref":
raise not_found()
context = parse_query_context(context_kind, context_id)
rights = element_rights(conn, principal.account_id, element, context)
if not rights.read:
raise not_found()
ref = conn.execute(
"""
SELECT source, external_id, detail, connector_id, resolution
FROM external_references WHERE element_id = %s
""",
(element_id,),
).fetchone()
return element, context, ref
def _complete_mail(conn, principal: Principal, element, context, ref):
module = get_source(ref["source"]) if ref is not None else None
if module is None or module.representation != "email":
raise unprocessable("Das ist keine E-Mail.")
opened = module.open_original(conn, principal.account_id, element, context, ref)
if isinstance(opened, RetrievalFailure):
raise unprocessable(opened.message)
raw = opened[0] if isinstance(opened, tuple) else opened
parsed = parse_mail(raw)
if parsed.missing:
names = ", ".join(parsed.missing[:5])
raise unprocessable(f"Eine Anlage der E-Mail ließ sich nicht vollständig lesen: {names}.")
return parsed, raw
@router.get("/api/v1/external-refs/{element_id}/mail/original")
def download_mail(
element_id: UUID,
context_kind: str | None = None,
context_id: str | None = None,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
element, context, ref = _opened_ref(conn, principal, element_id, context_kind, context_id)
_parsed, raw = _complete_mail(conn, principal, element, context, ref)
return _mail_bytes(raw, "message/rfc822", "nachricht.eml")
@router.get("/api/v1/external-refs/{element_id}/mail/attachments/{index}")
def download_mail_attachment(
element_id: UUID,
index: int,
context_kind: str | None = None,
context_id: str | None = None,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
element, context, ref = _opened_ref(conn, principal, element_id, context_kind, context_id)
parsed, _raw = _complete_mail(conn, principal, element, context, ref)
if index < 0 or index >= len(parsed.attachments):
raise not_found()
item = parsed.attachments[index]
return _mail_bytes(item.data, item.media_type or "application/octet-stream", item.filename, inline=True)
def _mail_bytes(data: bytes, media_type: str, filename: str, inline: bool = False) -> Response:
disposition = content_disposition(filename)
if inline:
disposition = disposition.replace("attachment;", "inline;", 1)
return Response(
content=data,
media_type=media_type,
headers={
**_PRIVATE,
"Content-Disposition": disposition,
},
)
@router.get("/api/v1/sources/paperless/documents")
def search_paperless(
q: str = "",
connector_id: UUID | None = None,
title: str = "",
correspondent: str = "",
document_type: str = "",
tag: str = "",
document_from: str = "",
document_to: str = "",
sort: str = "",
cursor: str = "",
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
return _run_search(
"paperless",
conn,
principal.account_id,
q.strip(),
connector_id,
"",
None,
{
"title": title,
"correspondent": correspondent,
"document_type": document_type,
"tag": tag,
"document_from": document_from,
"document_to": document_to,
"sort": sort,
"cursor": cursor,
},
)
@router.get("/api/v1/sources/{kind}/facets")
def source_facets(
kind: str,
connector_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
module = require_source(kind)
if module.facets is None:
raise unsupported("Diese Quelle hat keine Auswahllisten.")
return module.facets(conn, principal.account_id, connector_id)
@router.get("/api/v1/sources/paperless/documents/{document_id}/preview")
def preview_paperless_document(
document_id: str,
connector_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
data, media, name = paperless_content(conn, principal.account_id, document_id, connector_id)
return Response(
content=data,
media_type=media,
headers={**_PRIVATE, "Content-Disposition": content_disposition(name).replace("attachment;", "inline;", 1)},
)
@router.get("/api/v1/sources/imap/mailboxes")
def list_mailboxes(
connector_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
return _run_navigate("imap", conn, principal.account_id, connector_id)
@router.get("/api/v1/sources/imap/messages")
def search_mail(
connector_id: UUID,
q: str = "",
mailbox: str = "",
before: int | None = None,
title: str = "",
correspondent: str = "",
document_type: str = "",
tag: str = "",
document_from: str = "",
document_to: str = "",
sort: str = "",
cursor: str = "",
uidvalidity: int | None = None,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
if before is not None and before < 1:
raise unprocessable("Die Seitenangabe ist ungültig.")
return _run_search(
"imap",
conn,
principal.account_id,
q.strip(),
connector_id,
mailbox.strip(),
before,
{
"title": title,
"correspondent": correspondent,
"document_type": document_type,
"tag": tag,
"document_from": document_from,
"document_to": document_to,
"sort": sort,
"cursor": cursor,
},
uidvalidity,
)
@router.get("/api/v1/sources/imap/message")
def read_mail(
connector_id: UUID,
mailbox: str,
uid: int,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
if uid < 1:
raise unprocessable("Die Nachricht ist ungültig.")
return imap_preview(conn, principal.account_id, connector_id, mailbox.strip(), uid)
@router.post("/api/v1/sources/link", status_code=201)
def link_source(body: ExternalIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
if get_source(body.source) is None:
raise unprocessable("Verknüpft werden registrierte Quellen.")
element = create_external(
conn,
principal.account_id,
principal.scope_id,
body.title,
body.source,
body.external_id,
Ctx(body.context.kind, body.context.id),
_ctx_model(body.placement),
body.chapter_id,
body.dates.document_on,
body.dates.sent_on,
body.dates.received_on,
body.detail.model_dump(mode="json", exclude_none=True) if body.detail else None,
)
return _created(f"/api/v1/elements/{element['id']}", {"id": str(element["id"]), "title": element["title"]})
@router.post("/api/v1/external-refs/{element_id}/assignment")
def assign_source(
element_id: UUID,
body: SourceAssignmentIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
assign_reference(conn, principal.account_id, element_id, body.connector_id)
return {"id": str(element_id), "connector_id": str(body.connector_id), "resolution": "bound"}
def _connector_parts(body: ConnectorIn, current: dict | None) -> tuple[str, dict, str]:
"""The registered module validates. Flat fields of the first release are folded into ``config``."""
flat = body.model_dump(exclude={"kind", "name", "config"})
return parse_connector(body.kind, body.name, flat, body.config, current)
_SEARCH_FLAGS = {
"title": "title",
"correspondent": "correspondent",
"document_type": "document_type",
"tag": "tags",
"document_from": "document_range",
"document_to": "document_range",
"sort": "sort",
"cursor": "continuation",
}
def _run_search(kind: str, conn, owner, query: str, connector_id: UUID | None, mailbox: str, before: int | None, filters: dict, uidvalidity: int | None = None) -> dict:
module = require_source(kind)
search = module.capabilities["search"]
refused = [name for name, value in filters.items() if str(value or "").strip() and not search.get(_SEARCH_FLAGS.get(name, name))]
if before is not None and not search.get("continuation"):
refused.append("before")
if refused:
raise unsupported("Diese Suche unterstützt den Filter nicht: " + ", ".join(refused) + ".")
options = {"mailbox": mailbox, "before": before}
if uidvalidity is not None:
options["uidvalidity"] = uidvalidity
options.update({key: value for key, value in filters.items() if str(value or "").strip()})
found = module.find(conn, owner, connector_id, query, options)
bound = str(found.get("connector_id") or connector_id or "")
return with_capabilities(kind, bound, found)
def _run_navigate(kind: str, conn, owner, connector_id: UUID) -> dict:
module = require_source(kind)
if not module.capabilities.get("navigate") or module.navigate is None:
raise unsupported("Diese Quelle hat keine Fachnavigation.")
return {"items": module.navigate(conn, owner, connector_id)}
@router.get("/api/v1/sources/{kind}/search")
def search_source(
kind: str,
q: str = "",
connector_id: UUID | None = None,
mailbox: str = "",
before: int | None = None,
title: str = "",
correspondent: str = "",
document_type: str = "",
tag: str = "",
document_from: str = "",
document_to: str = "",
sort: str = "",
cursor: str = "",
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
if before is not None and before < 1:
raise unprocessable("Die Seitenangabe ist ungültig.")
return _run_search(
kind,
conn,
principal.account_id,
q.strip(),
connector_id,
mailbox.strip(),
before,
{
"title": title,
"correspondent": correspondent,
"document_type": document_type,
"tag": tag,
"document_from": document_from,
"document_to": document_to,
"sort": sort,
"cursor": cursor,
},
)
@router.get("/api/v1/sources/{kind}/navigate")
def navigate_source(
kind: str,
connector_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
return _run_navigate(kind, conn, principal.account_id, connector_id)
@router.get("/api/v1/sources/{kind}/preview")
def preview_source(
kind: str,
connector_id: UUID,
mailbox: str = "",
uid: int = 0,
item: str = "",
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
module = require_source(kind)
if not module.capabilities.get("read_preview") or module.preview is None:
raise unsupported("Diese Quelle hat keine Vorschau vor dem Übernehmen.")
return module.preview(conn, principal.account_id, connector_id, {"mailbox": mailbox, "uid": uid, "item": item})