lukasandClaude Opus 4.8
4e077f1a37
Backend foundation for the plugin platform (SPEC §11), Phases 1-3.
Phase 1 — SDK + loader:
- app/plugins/types.py: frozen Plugin/UiManifest/Slot/Page/JobSpec contract.
- app/plugins/sdk.py: sdk(name) facade — the only app.* import allowed for plugins
(scoped session, plugin.{name}.* publish, blob, outbox, settings, SSRF http_get, KV, enqueue).
- app/plugins/loader.py: entry-point discovery (webmail.plugins), hook forwarding
(API + worker), router mounting at /api/plugins/{name}, ui-manifest aggregation.
- plugin_kv core table (migration 0013) + GET /api/plugins/ui-manifest.
Phase 2 — non-removable core plugins + DB-enforced privacy:
- builtin flag (calendar/contacts will be builtin=True; uninstall refuses them).
- RLS per-user isolation on plg_* tables: least-privilege webmail_plugin role
(migration 0014), plugin_session(user_id) sets LOCAL ROLE + app.current_user_id,
rls.enable_rls() (ENABLE+FORCE RLS + USING/WITH CHECK policy). Mail untouched.
- Per-plugin Alembic runner (shared env, dedicated version table) + install/uninstall
--drop-data CLI; skeleton fixture proves install -> run -> uninstall --drop-data
leaves zero residue (§12 M3 acceptance).
Phase 3 — plugin jobs (§11.2):
- JobSpec registered as arq function plg.{plugin}.{func} + cron (5-field parser);
singleton=True guarded by a per-(plugin,user) Redis lock; wired onto the shared
interactive worker.
Gates: ruff, mypy --strict (94 files + tests), full suite 326 passed. RLS isolation,
migration round-trip, and singleton lock covered by tests.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rcj3TpydMTzTSmU7kunzf8
117 lines
4.1 KiB
Python
117 lines
4.1 KiB
Python
"""The plugin SDK — the ONLY ``app.*`` surface a plugin may import (SPEC §11).
|
|
|
|
Everything a plugin needs is reached through :func:`sdk`, which returns a
|
|
:class:`PluginSdk` bound to the plugin's name: a plugin-scoped DB session, the
|
|
event bus (publishing under ``plugin.{name}.*``), the blob store, outbox
|
|
draft/send helpers, the settings accessor, an SSRF-guarded HTTP client
|
|
(§10.6), and the namespaced KV store (§11).
|
|
|
|
The frozen contract types (:class:`Plugin`, :class:`UiManifest`, :class:`JobSpec`,
|
|
…) are re-exported here so plugin packages import only from ``app.plugins.sdk``.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import uuid
|
|
from contextlib import AbstractAsyncContextManager
|
|
from dataclasses import dataclass
|
|
from typing import Any
|
|
|
|
from sqlalchemy.ext.asyncio import AsyncSession
|
|
|
|
from app.accounts.ssrf import guarded_get
|
|
from app.config import Settings, get_settings
|
|
from app.events import get_event_bus
|
|
from app.indexer import blobstore
|
|
from app.outbox import service as outbox_service
|
|
from app.plugins.db import plugin_session
|
|
from app.plugins.kv import PluginKvStore
|
|
from app.plugins.types import (
|
|
Hook,
|
|
JobFunc,
|
|
JobSpec,
|
|
Page,
|
|
PageNav,
|
|
Plugin,
|
|
Slot,
|
|
UiManifest,
|
|
)
|
|
from app.queue import enqueue_job
|
|
|
|
__all__ = [
|
|
"Hook",
|
|
"JobFunc",
|
|
"JobSpec",
|
|
"Page",
|
|
"PageNav",
|
|
"Plugin",
|
|
"PluginSdk",
|
|
"Slot",
|
|
"UiManifest",
|
|
"blobstore",
|
|
"sdk",
|
|
]
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class PluginSdk:
|
|
"""A lightweight facade over shared services, scoped to one plugin.
|
|
|
|
Cheap to construct (wraps process-wide singletons + the plugin name), so
|
|
handlers/routes obtain it on demand via ``sdk("<name>")``."""
|
|
|
|
name: str
|
|
|
|
# --- config -------------------------------------------------------------
|
|
@property
|
|
def settings(self) -> Settings:
|
|
return get_settings()
|
|
|
|
# --- database -----------------------------------------------------------
|
|
def session(self, user_id: uuid.UUID) -> AbstractAsyncContextManager[AsyncSession]:
|
|
"""An RLS-enforced transactional session scoped to ``user_id`` (SPEC §11.1).
|
|
|
|
Row-level security limits every query to this user's rows on ``plg_*``
|
|
tables — even a query that forgets ``WHERE user_id`` cannot leak or write
|
|
across users (see :mod:`app.plugins.db`)."""
|
|
return plugin_session(user_id)
|
|
|
|
def kv(self, user_id: uuid.UUID) -> PluginKvStore:
|
|
"""The namespaced KV store for this plugin and ``user_id`` (SPEC §11)."""
|
|
return PluginKvStore(self.name, user_id)
|
|
|
|
# --- events -------------------------------------------------------------
|
|
async def publish(self, event: str, payload: dict[str, object]) -> None:
|
|
"""Publish ``plugin.{name}.{event}`` on the bus (payload needs ``user_id``)."""
|
|
await get_event_bus().publish(f"plugin.{self.name}.{event}", payload)
|
|
|
|
# --- background jobs ----------------------------------------------------
|
|
async def enqueue(self, job_func: JobFunc, **kwargs: Any) -> None:
|
|
"""Enqueue one of this plugin's jobs on the shared worker (SPEC §11.2).
|
|
|
|
``job_func`` must be a job declared in this plugin's ``jobs=[...]``. Pass
|
|
``user_id=`` for singleton jobs so the per-user lock applies."""
|
|
await enqueue_job(f"plg.{self.name}.{job_func.__name__}", **kwargs)
|
|
|
|
# --- blob store ---------------------------------------------------------
|
|
@property
|
|
def blob(self) -> object:
|
|
"""The blob store (``store``/``load``/``exists``/``remove``), keyed by user."""
|
|
return blobstore
|
|
|
|
# --- outbox -------------------------------------------------------------
|
|
@property
|
|
def outbox(self) -> object:
|
|
"""Draft/send helpers (``upsert_draft``, ``create_outbox``, …)."""
|
|
return outbox_service
|
|
|
|
# --- outbound HTTP ------------------------------------------------------
|
|
async def http_get(self, url: str) -> str | None:
|
|
"""GET ``url`` through the §10.6 SSRF guard (blocks private IPs/oversize)."""
|
|
return await guarded_get(url)
|
|
|
|
|
|
def sdk(name: str) -> PluginSdk:
|
|
"""Return the SDK facade bound to plugin ``name`` (SPEC §11)."""
|
|
return PluginSdk(name)
|