keepup-admin 0.3.0__tar.gz → 0.4.0__tar.gz

{keepup_admin-0.3.0/keepup_admin.egg-info → keepup_admin-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keepup-admin
-Version: 0.3.0
+Version: 0.4.0
 Summary: An admin framework over FastAPI: plugins, panel, users, replicas
 Author-email: Fedor Sergeev <fksergeev@gmail.com>
 License-Expression: Apache-2.0
@@ -22,10 +22,7 @@ Requires-Dist: fastapi<1,>=0.128
 Requires-Dist: starlette<2,>=1.3.1
 Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: sqlalchemy<3,>=2.0
-Requires-Dist: psycopg2-binary>=2.9
 Requires-Dist: apscheduler<4,>=3.10
-Requires-Dist: bcrypt<5,>=4.0
-Requires-Dist: pyjwt[crypto]<3,>=2.15
 Requires-Dist: python-multipart>=0.0.31
 Requires-Dist: PyYAML<7,>=6.0
 Requires-Dist: psutil>=7.0
@@ -39,8 +36,32 @@ Requires-Dist: pytest>=8; extra == "test"
 Requires-Dist: pytest-asyncio>=0.24; extra == "test"
 Requires-Dist: pytest-cov>=5; extra == "test"
 Requires-Dist: uvicorn>=0.30; extra == "test"
+Provides-Extra: db
+Requires-Dist: keepup-db>=0.4.0; extra == "db"
+Provides-Extra: auth
+Requires-Dist: keepup-auth>=0.4.0; extra == "auth"
+Provides-Extra: users
+Requires-Dist: keepup-users>=0.4.0; extra == "users"
+Provides-Extra: ui
+Requires-Dist: keepup-ui>=0.4.0; extra == "ui"
+Provides-Extra: audit
+Requires-Dist: keepup-audit>=0.4.0; extra == "audit"
+Provides-Extra: metrics
+Requires-Dist: keepup-metrics>=0.4.0; extra == "metrics"
+Provides-Extra: integration-log
+Requires-Dist: keepup-integration-log>=0.4.0; extra == "integration-log"
+Provides-Extra: panel
+Requires-Dist: keepup-db>=0.4.0; extra == "panel"
+Requires-Dist: keepup-auth>=0.4.0; extra == "panel"
+Requires-Dist: keepup-users>=0.4.0; extra == "panel"
+Requires-Dist: keepup-ui>=0.4.0; extra == "panel"
+Requires-Dist: keepup-audit>=0.4.0; extra == "panel"
+Requires-Dist: keepup-metrics>=0.4.0; extra == "panel"
+Requires-Dist: keepup-integration-log>=0.4.0; extra == "panel"
 Provides-Extra: postgres
-Requires-Dist: asyncpg>=0.31; extra == "postgres"
+Requires-Dist: keepup-postgres>=0.4.0; extra == "postgres"
+Provides-Extra: sqlite
+Requires-Dist: keepup-sqlite>=0.4.0; extra == "sqlite"
 Dynamic: license-file
 
 # keepup
@@ -125,16 +146,17 @@ between replicas needs.
 ## Tests
 
 ```bash
-pip install -e ".[test]"
+pip install -e ".[test]" -e packages/keepup-*
 pytest tests/
 ```
 
 **Install first, then test.** Pointing pytest at the checkout does not work on
 its own: `import keepup` has to resolve, and the directory a clone lands in is
 called `keepup-admin`, so nothing is named `keepup` until the package is
-installed. The `test` extra carries what the suite needs beyond the package —
-notably `cryptography`, which the framework itself never imports and the OIDC
-tests sign tokens with.
+installed. The capabilities are distributions of their own in `packages/` —
+each carries the libraries it needs, and the suite imports them — so a clone
+installs them from the tree; the extras name the same ones for an installation
+from the index.
 
 The suite runs against SQLite with no network, needs no application beside the
 package, and holds a coverage floor declared in `pyproject.toml`. Checks that

{keepup_admin-0.3.0 → keepup_admin-0.4.0}/README.md

@@ -80,16 +80,17 @@ between replicas needs.
 ## Tests
 
 ```bash
-pip install -e ".[test]"
+pip install -e ".[test]" -e packages/keepup-*
 pytest tests/
 ```
 
 **Install first, then test.** Pointing pytest at the checkout does not work on
 its own: `import keepup` has to resolve, and the directory a clone lands in is
 called `keepup-admin`, so nothing is named `keepup` until the package is
-installed. The `test` extra carries what the suite needs beyond the package —
-notably `cryptography`, which the framework itself never imports and the OIDC
-tests sign tokens with.
+installed. The capabilities are distributions of their own in `packages/` —
+each carries the libraries it needs, and the suite imports them — so a clone
+installs them from the tree; the extras name the same ones for an installation
+from the index.
 
 The suite runs against SQLite with no network, needs no application beside the
 package, and holds a coverage floor declared in `pyproject.toml`. Checks that

{keepup_admin-0.3.0 → keepup_admin-0.4.0}/__init__.py

@@ -26,6 +26,12 @@ except Exception:
     # itself, until the applications switch to installing by version.
     __version__ = "0.0.0+source"
 
+# Names that moved into a distribution of their own keep working for one
+# release, and say where they went (keepup-114, keepup-124).
+from keepup import compat as _compat
+
+_compat.install()
+
 __all__ = ["KeepupSettings", "StaticMount", "create_app", "__version__"]
 
 

{keepup_admin-0.3.0 → keepup_admin-0.4.0}/audit.py

@@ -22,8 +22,6 @@ from contextlib import asynccontextmanager
 from datetime import datetime
 from typing import Any, Dict, Optional
 
-from sqlalchemy import CheckConstraint, Column, DateTime, Index, Integer, Text, UniqueConstraint
-from sqlalchemy.dialects import postgresql
 
 from keepup import retention, tables
 from keepup.db import DatabaseManagerV2, db_config
@@ -48,6 +46,10 @@ __all__ = [
     "retention_days",
 ]
 
+# The audit capability declares its own tables (keepup-124); re-exported here so
+# the path that predates the catalogue still creates them.
+from keepup_audit.tables import INCOMING_REQUESTS  # noqa: E402
+
 logger = logging.getLogger(__name__)
 
 incoming_requests_buffer: Dict[str, Dict[str, Any]] = {}
@@ -389,33 +391,6 @@ async def audit_retention_background():
             await asyncio.sleep(AUDIT_ERROR_BACKOFF_SECONDS)
 
 
-INCOMING_REQUESTS = tables.table(
-    "incoming_requests",
-    tables.auto_id(),
-    Column("instance_id", Text, nullable=False),
-    Column("method", Text, nullable=False),
-    Column("endpoint", Text, nullable=False),
-    Column("host", Text, nullable=False),
-    Column("request_data", postgresql.JSONB().with_variant(Text(), "sqlite")),
-    Column("request_start_at", DateTime, nullable=False),
-    Column("request_end_at", DateTime),
-    Column("duration_ms", Integer),
-    Column("http_status", Integer),
-    Column("response_data", postgresql.JSONB().with_variant(Text(), "sqlite")),
-    Column("error_message", Text),
-    Column("created_at", DateTime, server_default=tables.NOW),
-    UniqueConstraint("instance_id", "method", "endpoint", "request_start_at",
-                     name="incoming_requests_instance_method_endpoint_unique").ddl_if(dialect="postgresql"),
-    CheckConstraint("duration_ms >= 0",
-                    name="incoming_requests_check_duration").ddl_if(dialect="postgresql"),
-    CheckConstraint("(http_status IS NULL) OR (http_status >= 100 AND http_status <= 599)",
-                    name="incoming_requests_check_http_status").ddl_if(dialect="postgresql"),
-    Index("incoming_requests_instance_method_endpoint_unique",
-          "instance_id", "method", "endpoint", "request_start_at", unique=True).ddl_if(dialect="sqlite"),
-    Index("idx_incoming_requests_instance_id", "instance_id"),
-    Index("idx_incoming_requests_endpoint", "endpoint"),
-    Index("idx_incoming_requests_created_at", "created_at"),
-)
 
 
 def init_incoming_requests_table():

keepup_admin-0.4.0/builtin/audit.py

@@ -0,0 +1,107 @@
+"""The audit: incoming calls, the application's events and the administrator's trail.
+
+Task keepup-111. These live in three modules of the kernel -- ``audit.py``
+(incoming requests, redaction, retention), ``events.py`` (the application's own
+event log) and ``admin_trail.py`` (what an administrator decided) -- and all
+three import SQLAlchemy, so the base bundle cannot be assembled without a
+database library while they stay. The plugin here owns the two tables and
+publishes the two services; the kernel's own trail and the route wrapper reach
+them through the names (``keepup/kernel/observability.py``), not by importing
+these modules.
+
+The routes of the event log and the section that shows it travel with the panel
+(keepup-104); what is here is the recording itself, its retention and the two
+names.
+"""
+
+import logging
+from typing import Any, Dict, List
+
+from keepup.kernel.datasource import SERVICE_DATASOURCE
+from keepup.kernel.descriptor import KIND_OPTIONAL, PluginDescriptor
+from keepup.kernel.observability import SERVICE_AUDIT, SERVICE_EVENTS, Recording
+from keepup.audit import INCOMING_REQUESTS
+from keepup.events import APP_EVENTS
+from keepup.plugins.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["AuditPlugin", "AuditRecording"]
+
+
+class AuditRecording(Recording):
+    """The framework's own recording, behind the kernel's two names.
+
+    It delegates to the modules that already do the work (``keepup.audit``,
+    ``keepup.events``) so that nothing changes for a deployment today; those
+    modules travel into this capability's distribution in keepup-124.
+    """
+
+    def __init__(self, datasource: Any = None):
+        from keepup.audit import IncomingRequestLogger, log_api_request
+
+        super().__init__(start=log_api_request, end=IncomingRequestLogger.end_request,
+                         name="keepup audit")
+
+    def watch(self, emitter: Any) -> None:
+        """Add another emitter, for a capability that keeps events of its own."""
+        self.emitters.append(emitter)
+
+
+class AuditPlugin(BasePlugin):
+    """The capability: two tables, two services and the retention they need."""
+
+    descriptor = PluginDescriptor(
+        id="audit",
+        name="Event audit",
+        version="0.4.0",
+        distribution="keepup-audit",
+        kind=KIND_OPTIONAL,
+        priority=60,
+        provides=("audit>=1", "events>=1"),
+        requires=("datasource>=1",),
+        wants=("locks>=1", "scheduler>=1"),
+        contributions=("routes", "sections", "tables", "events"),
+    )
+
+    def __init__(self, config=None):
+        super().__init__("audit", "Event audit", config)
+
+    def register(self, services):
+        """Publish the recording where there is a data source to write it to.
+
+        Args:
+            services: the runtime's registry.
+        """
+        if services.has(SERVICE_DATASOURCE):
+            self.recording = AuditRecording(services.require(SERVICE_DATASOURCE))
+            services.provide(SERVICE_AUDIT, self.recording, version=1, plugin_id="audit")
+            services.provide(SERVICE_EVENTS, self.recording, version=1, plugin_id="audit")
+
+    async def initialize(self):
+        """Keep the recording published at registration; build one if there is none."""
+        if getattr(self, "recording", None) is None:
+            self.recording = AuditRecording(self.services.require(SERVICE_DATASOURCE))
+        return True
+
+    def get_declared_tables(self):
+        """The two tables this capability owns, declared once, until keepup-124."""
+        return [INCOMING_REQUESTS, APP_EVENTS]
+
+    def get_event_sinks(self) -> List[Any]:
+        """What writes an event down, for the kernel's own trail."""
+        return [self.emit]
+
+    async def emit(self, event_type: str, payload: Dict[str, Any] = None) -> None:
+        """Write one event through the module that still owns the table."""
+        from keepup.events import emit_event
+
+        await emit_event(event_type, payload or {})
+
+    def get_api_routes(self):
+        """No routes yet: the event log's own travel with the panel (keepup-104)."""
+        return []
+
+    def get_handlers(self):
+        """What another plugin may reach instead of importing the audit."""
+        return {"recording": self.recording, "emit": self.emit}

keepup_admin-0.4.0/builtin/auth.py

@@ -0,0 +1,100 @@
+"""Sign-in as a capability: who is calling, and what they may do.
+
+Task keepup-116, first half. The kernel owns the shapes and the two names
+(``keepup/kernel/security.py``, keepup-119); this plugin is a deployment putting
+an answer behind them, and the tables that answer needs -- the panel's sessions
+and the login attempts that throttle a guesser -- belong to it.
+
+The sign-in machinery itself (``auth/routes.py``, ``panel_session.py``,
+``login_throttle.py``, the providers, OIDC and somebody else's identity system)
+travels into this capability's distribution in keepup-124, together with the
+routes, the sockets and the CSRF middleware it contributes. What is here is the
+claim: two services, two tables, and an identity the runtime adopts.
+"""
+
+import logging
+from typing import Any, Dict, List
+
+from keepup.kernel.datasource import SERVICE_DATASOURCE
+from keepup.kernel.descriptor import KIND_OPTIONAL, PluginDescriptor
+from keepup.kernel.security import SERVICE_AUTH, SERVICE_PERMISSIONS, Identity
+from keepup.plugins.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["AuthPlugin", "build_identity"]
+
+
+def build_identity(name: str = "keepup-auth") -> Identity:
+    """The framework's own sign-in, behind the shape the kernel owns.
+
+    Args:
+        name: what to call it in a log line.
+
+    Returns:
+        The identity: how a caller is found, and what decides a right.
+    """
+    from keepup.auth.dependencies import get_panel_user
+    from keepup.auth.identity import access
+
+    return Identity(subject_dependency=get_panel_user, checker=access.check, name=name)
+
+
+class AuthPlugin(BasePlugin):
+    """The capability: sessions, attempts, and the two services that answer."""
+
+    descriptor = PluginDescriptor(
+        id="auth",
+        name="Sign-in and sessions",
+        version="0.4.0",
+        distribution="keepup-auth",
+        kind=KIND_OPTIONAL,
+        priority=30,
+        provides=("auth>=1", "permissions>=1"),
+        requires=("datasource>=1",),
+        contributions=("routes", "sockets", "middleware", "tables", "permissions"),
+    )
+
+    def __init__(self, config=None):
+        super().__init__("auth", "Sign-in and sessions", config)
+
+    def register(self, services):
+        """Publish the identity under both names, once there is storage.
+
+        Args:
+            services: the runtime's registry.
+        """
+        if services.has(SERVICE_DATASOURCE):
+            self.identity = build_identity()
+            services.provide(SERVICE_AUTH, self.identity, version=1, plugin_id="auth")
+            services.provide(SERVICE_PERMISSIONS, self.identity, version=1, plugin_id="auth")
+
+    async def initialize(self):
+        """Keep the identity published at registration; build one if there is none."""
+        if getattr(self, "identity", None) is None:
+            self.identity = build_identity()
+        return True
+
+    def get_declared_tables(self) -> List[Any]:
+        """The two tables this capability owns, declared once, until keepup-124."""
+        from keepup.auth.login_throttle import LOGIN_ATTEMPTS
+        from keepup.auth.panel_session import AUTH_SESSION
+
+        return [AUTH_SESSION, LOGIN_ATTEMPTS]
+
+    def get_route_permissions(self) -> Dict[str, Any]:
+        """The rights this capability's routes ask for, by name.
+
+        Empty here, and declared all the same: the kind of contribution is what
+        another plugin reads to know that a right it asks for exists.
+        """
+        return {}
+
+    def get_api_routes(self) -> List[Any]:
+        """No routes yet: the sign-in's own (sign in, out, refresh, WebSocket, CSRF)
+        travel into this capability's distribution in keepup-124."""
+        return []
+
+    def get_handlers(self) -> Dict[str, Any]:
+        """What another plugin may reach instead of importing the sign-in."""
+        return {"identity": self.identity}

keepup_admin-0.4.0/builtin/db.py

@@ -0,0 +1,172 @@
+"""The data source as a plugin: the abstraction that holds the database library.
+
+Task keepup-124, first slice. `keepup/kernel/datasource.py` owns the shapes and
+the two names (keepup-106), the drivers answer with `spec()` (keepup-107,
+keepup-108) -- and nobody published `datasource`, so no capability could reach
+storage through it. This is the plugin that does: it requires a driver, publishes
+the service built on the framework's current manager (`keepup.db`), and creates
+nothing itself except what capabilities declare.
+
+It answers the abstraction with the manager, so the dialect, the pool and the
+creation of declared tables stay where they are today and move into
+`packages/keepup-db` in the rest of keepup-124. What is fixed here is the part
+that cannot be deferred: `keepup-admin` plus `keepup-db` plus one driver is a
+deployment that talks to a database, and every capability asks it by name.
+"""
+
+import logging
+from typing import Any, Dict, List, Mapping, Optional
+
+from keepup.db import DatabaseManagerV2, db_config
+from keepup.kernel.datasource import (
+    SERVICE_DATASOURCE,
+    SERVICE_DATASOURCE_DRIVER,
+    DriverSpec,
+)
+from keepup.kernel.descriptor import KIND_REQUIRED, PluginDescriptor
+from keepup.plugins.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["DbPlugin", "DatabaseSource", "SERVICE_DATASOURCE"]
+
+
+class DatabaseSource:
+    """The framework's manager, wearing the abstraction's shape.
+
+    Everything a capability may ask for is here and nothing else: run a
+    statement, run one that changes something, create what was declared, close.
+    Which database this is comes from the driver, not from here.
+    """
+
+    def __init__(self, manager: Any, spec: Optional[DriverSpec] = None):
+        self.manager = manager
+        self.spec = spec
+
+    @property
+    def dialect(self) -> str:
+        """The dialect the driver named, or the configured one."""
+        if self.spec is not None and self.spec.dialect:
+            return self.spec.dialect
+        return "postgresql" if db_config.is_postgres() else "sqlite"
+
+    async def execute(self, statement: str, params: Optional[Mapping[str, Any]] = None) -> Any:
+        """Run a statement and answer its rows."""
+        return await self.manager.execute_async(statement, dict(params or {}))
+
+    async def execute_one(self, statement: str,
+                          params: Optional[Mapping[str, Any]] = None) -> Optional[Dict[str, Any]]:
+        """Run a statement and answer its first row, or None."""
+        return await self.manager.execute_one_async(statement, dict(params or {}))
+
+    async def execute_commit(self, statement: str,
+                             params: Optional[Mapping[str, Any]] = None) -> Any:
+        """Run a statement that changes something, and commit it."""
+        return await self.manager.execute_commit_async(statement, dict(params or {}))
+
+    async def execute_many(self, statement: str, params: List[Mapping[str, Any]]) -> Any:
+        """Run one statement for every set of parameters."""
+        return await self.manager.execute_many_async(statement, [dict(item) for item in params])
+
+    def ensure_tables(self, *tables: Any) -> None:
+        """Create what the declaration says, and add the columns it gained.
+
+        The declarations come from the capabilities that own them, which is why
+        this takes them as arguments rather than knowing any itself.
+        """
+        from keepup import tables as table_language
+
+        flat = []
+        for table in tables:
+            flat.extend(table if isinstance(table, (list, tuple)) else [table])
+        created = [table for table in flat if table is not None]
+        if not created:
+            return
+        table_language.ensure_tables(*created)
+
+    def ensure_columns(self, table: Any) -> None:
+        """Add the columns an existing table lacks."""
+        from keepup import tables as table_language
+
+        table_language.ensure_columns(table)
+
+    def get_session(self) -> Any:
+        """A session, for a caller that needs a transaction."""
+        return self.manager.get_session()
+
+    def raw_connection(self) -> Any:
+        """A driver cursor, for code that has to go below the abstraction."""
+        return self.manager.raw_connection()
+
+    def pool_status(self) -> Any:
+        """What the pool is doing, for the metrics capability."""
+        reader = getattr(self.manager, "get_pool_status", None)
+        return reader() if callable(reader) else {}
+
+    def dispose(self) -> None:
+        """Close what this opened."""
+        self.manager.dispose()
+
+
+class DbPlugin(BasePlugin):
+    """The capability every other one needs: storage, by name."""
+
+    descriptor = PluginDescriptor(
+        id="db",
+        name="Database abstraction",
+        version="0.4.0",
+        distribution="keepup-db",
+        kind=KIND_REQUIRED,
+        priority=10,
+        provides=("datasource>=1",),
+        requires=("datasource_driver>=1",),
+        contributions=("tables",),
+    )
+
+    def __init__(self, config=None):
+        super().__init__("db", "Database abstraction", config)
+
+    def register(self, services):
+        """Publish the data source the driver describes.
+
+        Args:
+            services: the runtime's registry.
+        """
+        spec = None
+        if services.has(SERVICE_DATASOURCE_DRIVER):
+            driver = services.require(SERVICE_DATASOURCE_DRIVER)
+            spec = driver.spec() if callable(getattr(driver, "spec", None)) else None
+        self.source = DatabaseSource(DatabaseManagerV2, spec)
+        services.provide(SERVICE_DATASOURCE, self.source, version=1, plugin_id="db")
+        logger.info("The data source is %s", self.source.dialect)
+
+    async def initialize(self):
+        """Take the driver's description, and open nothing.
+
+        The driver is read here rather than at registration: a plugin's
+        ``register`` runs in the order the catalogue lists, and the abstraction
+        may well be listed before the driver it abstracts. By the time a phase
+        initialises, every plugin of it has registered.
+        """
+        if self.services.has(SERVICE_DATASOURCE_DRIVER):
+            driver = self.services.require(SERVICE_DATASOURCE_DRIVER)
+            reader = getattr(driver, "spec", None)
+            if callable(reader):
+                self.source.spec = reader()
+        return True
+
+    def get_declared_tables(self) -> List[Any]:
+        """Nothing: the abstraction owns no table of the framework's.
+
+        Every table belongs to the capability that keeps it there, which is what
+        makes `keepup-db` an abstraction rather than a schema (keepup-106).
+        """
+        return []
+
+    def get_api_routes(self) -> List[Any]:
+        """No routes: storage is reached by capabilities, not by people."""
+        return []
+
+    def get_handlers(self) -> Dict[str, Any]:
+        """What another plugin may reach instead of importing the manager."""
+        return {"service": self.source}