keepup-modules 0.5.0__py3-none-any.whl

keepup_modules/decisions.py

@@ -0,0 +1,281 @@
+"""What the deployment decided about each plugin, and the surface that shows it.
+
+Task keepup-113. The decision belongs to the modules capability: the kernel
+reads it while it composes the runtime -- a plugin an administrator switched off
+is not loaded at all -- and the panel shows it and changes it. The reading is
+what the kernel keeps (through `keepup.plugins.registry`, which asks this
+distribution and falls back to the file when it is not installed); the overrides
+themselves, the endpoints and the trail an administrator's change leaves live
+here.
+
+Three sources decide whether a declared plugin runs: its own flag in the
+configuration file, an administrator's override kept in this deployment's
+database, and the environment of this stand. The rule itself is
+``keepup.plugins.enablement``, which is pure; what lives here is everything
+around it that is not -- reading the file, reading and writing the overrides,
+and the administrative endpoints that report the decision and change it.
+
+The endpoints are the reason any of this is worth reporting at all. Once the
+server is up, a plugin that was switched off and a plugin that fell over look
+exactly the same from outside: the routes are absent and the server is
+healthy. The difference is kept by the manager and published here.
+"""
+
+import asyncio
+import json
+import logging
+import os
+from typing import Any, Dict
+
+from fastapi import Depends, HTTPException
+
+from keepup import clock
+from keepup_auth import user_roles
+from keepup_auth.dependencies import get_current_admin, get_current_user
+from keepup_audit import trail as admin_trail
+from keepup.plugins import enablement
+from keepup.plugins import route_mask
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = [
+    "clear_plugin_override",
+    "get_plugins",
+    "get_plugins_status",
+    "read_plugin_overrides",
+    "register_plugin_admin_routes",
+    "write_plugin_override",
+]
+
+logger = logging.getLogger(__name__)
+
+#: Where this deployment declares its plugins. The application names the file
+#: in KeepupSettings.plugins_config_path, and configure() is handed that value
+#: when the application is built; this is what a caller that never does reads.
+MODULES_CONFIG_PATH = 'config/modules.json'
+
+
+def configure(path: str = None) -> None:
+    """Where the administrative endpoints read the declared plugins from.
+
+    initialize_plugins() is handed the application's own path, and until this
+    existed the endpoints around it read the default instead: an application
+    that keeps its catalogue anywhere else answered 500 on the panel's plugin
+    report, and said so only in the log (keepup-93's integration test, run from
+    a directory without config/modules.json, is where it showed).
+    """
+    global MODULES_CONFIG_PATH
+    if path:
+        MODULES_CONFIG_PATH = path
+
+
+def read_plugin_overrides():
+    """What an administrator decided from the panel, per plugin (task 65).
+
+    Never fatal: a database that cannot answer must not keep the server from
+    starting. Without the overrides the file and the environment still decide,
+    which is the behaviour that existed before the panel could.
+    """
+    from keepup_db import DatabaseManagerV2
+    try:
+        rows = DatabaseManagerV2.execute(
+            "SELECT plugin_id, enabled FROM plugin_overrides", {})
+    except Exception as e:
+        logger.warning(f"Could not read plugin overrides, falling back to file and environment: {e}")
+        return {}
+    return {row["plugin_id"]: bool(row["enabled"]) for row in rows}
+
+
+def write_plugin_override(plugin_id: str, enabled: bool, changed_by=None) -> None:
+    """Record the panel's decision about one plugin, replacing any previous."""
+    from keepup_db import DatabaseManagerV2
+    updated = DatabaseManagerV2.execute_commit(
+        "UPDATE plugin_overrides SET enabled = :enabled, changed_by = :who, "
+        "changed_at = :now WHERE plugin_id = :pid",
+        {"enabled": enabled, "who": changed_by, "now": clock.utcnow(), "pid": plugin_id})
+    if not updated:
+        DatabaseManagerV2.execute_commit(
+            "INSERT INTO plugin_overrides (plugin_id, enabled, changed_by, changed_at) "
+            "VALUES (:pid, :enabled, :who, :now)",
+            {"pid": plugin_id, "enabled": enabled, "who": changed_by, "now": clock.utcnow()})
+
+
+def clear_plugin_override(plugin_id: str) -> None:
+    """Give the decision back to the file and the environment."""
+    from keepup_db import DatabaseManagerV2
+    DatabaseManagerV2.execute_commit(
+        "DELETE FROM plugin_overrides WHERE plugin_id = :pid", {"pid": plugin_id})
+
+
+def _declared_plugin_ids():
+    with open(MODULES_CONFIG_PATH, 'r', encoding='utf-8') as f:
+        config = json.load(f)
+    return {p["id"] for p in enablement.declared_plugins(config)}
+
+
+def _refuse_if_the_deployment_decides(plugin_id: str):
+    """A plugin named in the environment is not the panel's to switch.
+
+    Storing an override the environment would overrule is a trap: the
+    administrator switches it, restarts, and nothing changes. The refusal
+    names the reason instead.
+    """
+    if plugin_id not in _declared_plugin_ids():
+        raise HTTPException(status_code=404, detail="config/modules.json does not declare this plugin")
+    if enablement.decided_by_environment(plugin_id, os.environ):
+        raise HTTPException(
+            status_code=409,
+            detail=(f"This plugin is decided by the deployment: "
+                    f"{enablement.ENABLE_ENV}/{enablement.DISABLE_ENV} name it. "
+                    f"Change the environment of this stand and restart."))
+
+
+async def get_plugins(manager, current_user):
+    """The plugins available to this user: granted to a role of theirs and running.
+
+    A module-level function rather than only a closure of the route, because
+    this is the decision worth checking and a closure can be reached only
+    through the HTTP layer.
+
+    A user holds a set of roles, and the lists of all of them are glued together
+    -- each plugin once, however many of the roles name it (keepup-51).
+    """
+    try:
+        with open(MODULES_CONFIG_PATH, 'r', encoding='utf-8') as f:
+            config = json.load(f)
+
+        held = set(user_roles.held_by(current_user))
+        allowed_plugin_names = set()
+        for role in config.get('roles', []):
+            if role.get('name') in held:
+                allowed_plugin_names.update(role.get('plugins', []))
+
+        if not allowed_plugin_names:
+            return {"plugins": []}
+
+        # The role's list is visibility, not enablement: a plugin the role is
+        # shown but that did not come up has no routes to advertise.
+        available_plugins = []
+        for plugin_config in config.get('plugins', []):
+            if plugin_config.get('id') in allowed_plugin_names \
+                    and manager.get_plugin(plugin_config.get('id')) is not None:
+                available_plugins.append({
+                    "id": plugin_config.get('id'),
+                    "name": plugin_config.get('name'),
+                    "config": plugin_config.get('config', {})
+                })
+
+        return {"plugins": available_plugins}
+
+    except Exception as e:
+        logger.error(f"Error getting plugins: {str(e)}")
+        return {"plugins": []}
+
+
+async def get_plugins_status(manager, current_user=None):
+    """The state of every declared plugin.
+
+    Enabled or not and from where, loaded or not, initialised or not, and why.
+    An enabled plugin that did not come up is otherwise visible only as a line
+    in the start-up log.
+    """
+    try:
+        with open(MODULES_CONFIG_PATH, 'r', encoding='utf-8') as f:
+            config = json.load(f)
+        # Two resolutions: the snapshot taken at start-up is what is actually
+        # running, and the one computed now carries the panel's latest
+        # decisions. Where they differ, the row awaits a restart.
+        desired = enablement.resolve(
+            config, os.environ, overrides=await asyncio.to_thread(read_plugin_overrides))
+        return {"plugins": enablement.status_report(
+            config, manager.resolution, manager,
+            desired=desired, environ=os.environ)}
+    except Exception as e:
+        logger.error(f"Error reading plugin status: {str(e)}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+async def set_plugin_enabled(plugin_id: str, request: Dict[str, Any], admin: dict):
+    """Switch a backend plugin on or off from the panel.
+
+    Takes effect at the next start: the plugin's routes are built once, at
+    start-up, and are not removed from a running application.
+    """
+    _refuse_if_the_deployment_decides(plugin_id)
+    enabled = (request or {}).get("enabled")
+    if not isinstance(enabled, bool):
+        raise HTTPException(status_code=400, detail="Field 'enabled' must be true or false")
+    try:
+        await asyncio.to_thread(write_plugin_override, plugin_id, enabled,
+                                changed_by=admin.get("id"))
+    except Exception as e:
+        logger.error(f"Could not store the plugin override for {plugin_id}: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+    await admin_trail.record(admin_trail.PLUGIN_DECISION_CHANGED, admin,
+                             f"Plugin {plugin_id} {'enabled' if enabled else 'disabled'} "
+                             f"from the panel", plugin_id=plugin_id, enabled=enabled)
+    return {"success": True, "plugin_id": plugin_id, "enabled": enabled,
+            "pending_restart": True}
+
+
+async def clear_plugin_enabled(plugin_id: str, admin: dict = None):
+    """Give the decision about this plugin back to the file and the environment."""
+    _refuse_if_the_deployment_decides(plugin_id)
+    try:
+        await asyncio.to_thread(clear_plugin_override, plugin_id)
+    except Exception as e:
+        logger.error(f"Could not clear the plugin override for {plugin_id}: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+    await admin_trail.record(admin_trail.PLUGIN_DECISION_CHANGED, admin,
+                             f"Decision about plugin {plugin_id} given back to the file",
+                             plugin_id=plugin_id, enabled=None)
+    return {"success": True, "plugin_id": plugin_id}
+
+
+def register_plugin_admin_routes(app, manager):
+    """Register the plugin endpoints on the application."""
+
+    @app.get("/api/plugins")
+    async def get_plugins_endpoint(current_user: dict = Depends(get_current_user)):
+        """Return the plugins available to the current user."""
+        return await get_plugins(manager, current_user)
+
+    @app.get("/api/admin/plugins")
+    async def get_plugins_status_endpoint(admin: dict = Depends(get_current_admin)):
+        """The state of every declared plugin (administrators only)."""
+        return await get_plugins_status(manager, admin)
+
+    @app.get("/api/admin/route-masks")
+    async def get_route_masks_endpoint(admin: dict = Depends(get_current_admin)):
+        """The declared masks of every plugin route (administrators only).
+
+        Machine-readable on purpose: the point of declaring what a route
+        accepts is that a wrong request can be refused before the application,
+        at a gateway or a proxy, and neither of those can read a signature.
+
+        Behind the administrator's role because it is a map of the
+        application's surface -- not a secret, but not something to hand to
+        everybody who signed in either.
+        """
+        return {"routes": route_mask.describe_routes(manager.get_all_api_routes())}
+
+    @app.post("/api/admin/plugins/{plugin_id}/enabled")
+    async def set_plugin_enabled_endpoint(plugin_id: str, request: Dict[str, Any],
+                                          admin: dict = Depends(get_current_admin)):
+        """Switch a backend plugin on or off from the panel (administrators only)."""
+        return await set_plugin_enabled(plugin_id, request, admin)
+
+    @app.delete("/api/admin/plugins/{plugin_id}/enabled")
+    async def clear_plugin_enabled_endpoint(plugin_id: str,
+                                            admin: dict = Depends(get_current_admin)):
+        """Give the decision about this plugin back to the file (administrators only)."""
+        return await clear_plugin_enabled(plugin_id, admin)
+
+    # There is deliberately no route that calls a named handler by name.
+    # get_handlers() is how one plugin calls another inside the process, which
+    # is a trusted surface: a handler is written for a caller that has already
+    # decided who may do this, so many of them check nothing themselves.
+    # Published over HTTP it turned every such handler into an endpoint open to
+    # anybody signed in, and the difference between "no such plugin" and "no
+    # such handler" listed them for free (task keepup-10). A plugin publishes
+    # what it declares in get_api_routes(), and nothing besides.

keepup_modules/plugin.py

@@ -0,0 +1,120 @@
+"""The catalogue of panel sections as a capability (keepup-113).
+
+`modules.py` held the model -- which section exists, who may see it, where its
+files are -- in the kernel's package, together with the ten routes that manage
+it; `schema.py` created its two tables for every deployment, panel or not. The
+capability owns both now:
+
+* the model is the `catalogue` service, read on every request for a person's
+  roles (through the replica cache, which is why a section's change is published
+  to the other replicas);
+* the declaration of a section is *data*: the navigation fields are columns of
+  `frontend_modules` (`keepup_modules/tables.py`), and the file the framework
+  ships is imported into the database at start instead of being read by the
+  panel;
+* the import runs on the freeze (``post_construct``), because it is the union of
+  what the running plugins declare, the framework's own `sections.json` and the
+  application's `config/modules.json` -- the optional set is only known then
+  (doc/plugin_constructor.md, 9.1);
+* the decision about which backend plugins run is this capability's too
+  (`plugin_decisions`), because the kernel reads it without a panel.
+
+The ten routes are declared in `keepup_modules.catalogue` and registered by the
+application until the transport that mounts what a plugin declares exists
+(`keepup-http`, keepup-121).
+"""
+
+import asyncio
+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.plugins.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["ModulesPlugin", "SERVICE_CATALOGUE", "SERVICE_PLUGIN_DECISIONS"]
+
+#: What the panel asks for to know which sections a person may see.
+SERVICE_CATALOGUE = "catalogue"
+
+#: What the runtime reads to know what an administrator decided about a plugin.
+SERVICE_PLUGIN_DECISIONS = "plugin_decisions"
+
+
+class ModulesPlugin(BasePlugin):
+    """The catalogue of sections, and the decision about the plugins."""
+
+    descriptor = PluginDescriptor(
+        id="modules",
+        name="Module management",
+        version="0.5.0",
+        distribution="keepup-modules",
+        kind=KIND_OPTIONAL,
+        priority=70,
+        provides=(f"{SERVICE_CATALOGUE}>=1", f"{SERVICE_PLUGIN_DECISIONS}>=1"),
+        requires=("datasource>=1",),
+        contributions=("routes", "sections", "tables"),
+    )
+
+    def __init__(self, config=None):
+        super().__init__("modules", "Module management", config)
+
+    def register(self, services):
+        """Publish the catalogue model where there is a database to read it from."""
+        if services.has(SERVICE_DATASOURCE):
+            from keepup_modules import catalogue, decisions
+
+            services.provide(SERVICE_CATALOGUE, catalogue, version=1, plugin_id="modules")
+            services.provide(SERVICE_PLUGIN_DECISIONS, decisions, version=1,
+                             plugin_id="modules")
+
+    async def initialize(self):
+        """Nothing to build: the tables are the data source's, the import is the freeze's."""
+        return True
+
+    async def post_construct(self):
+        """Import what the sections declare, now that every plugin is known.
+
+        Idempotent, and the same rule for both files: the fields that are code
+        are the declaring plugin's and are re-pointed, while the name, the
+        description, `is_active` and the grants are the administrator's and are
+        only ever inserted (doc/plugin_constructor.md, 9.1).
+        """
+        settings = getattr(self.plugin_manager, "settings", None)
+        path = getattr(settings, "plugins_config_path", None)
+        from keepup_modules.catalogue import (import_declared_sections,
+                                              set_running_plugins,
+                                              sync_framework_sections,
+                                              sync_new_modules_from_json)
+
+        added = await asyncio.to_thread(sync_framework_sections)
+        declared = await asyncio.to_thread(sync_new_modules_from_json, path)
+        # What the running plugins declare themselves, each attributed to the
+        # plugin that declared it: a section of a plugin that does not run is
+        # not in the panel, and the row waits for it to come back (keepup-113).
+        plugins = getattr(self.plugin_manager, "loaded_plugins", {}) or {}
+        for plugin_id, plugin in sorted(plugins.items()):
+            sections = plugin.get_panel_sections() if hasattr(plugin, "get_panel_sections") else []
+            if sections:
+                await asyncio.to_thread(import_declared_sections,
+                                        {"modules": list(sections)}, plugin_id)
+        set_running_plugins(plugins)
+        logger.info("Catalogue imported: %s framework section(s), %s declared; %s plugin(s) running",
+                    added, declared, len(plugins))
+
+    def get_declared_tables(self) -> List[Any]:
+        """The catalogue's tables, declared by the capability that owns them."""
+        from keepup_modules.tables import FRONTEND_MODULES, PLUGIN_OVERRIDES, ROLE_MODULES
+
+        return [FRONTEND_MODULES, ROLE_MODULES, PLUGIN_OVERRIDES]
+
+    def get_api_routes(self) -> List[Dict[str, Any]]:
+        """No routes yet: the application registers the ten through the bridge."""
+        return []
+
+    def get_handlers(self) -> Dict[str, Any]:
+        from keepup_modules import catalogue
+
+        return {"catalogue": catalogue}

keepup_modules/tables.py

@@ -0,0 +1,81 @@
+"""The catalogue's tables, declared where the capability lives.
+
+Task keepup-113. `frontend_modules` was declared by the panel's distribution
+because the panel drew the navigation from it; the model -- which section exists,
+who may see it, where its files are -- is the catalogue's, so the declaration
+travels with the catalogue. `keepup_db.schema`, which re-exported all three for
+one
+release, which is what a path written before the split still imports.
+
+The navigation fields are columns now and not a JSON blob: the collapsed
+navigation is rendered from `icon`, the order from `nav_order`, and
+`declared_by` is what lets a section be filtered by the plugin that declared it
+(doc/plugin_constructor.md, section 9.1).
+"""
+
+from sqlalchemy import (Boolean, Column, DateTime, Index, Integer, Text,
+                        UniqueConstraint)
+from sqlalchemy import text as sql_text
+
+from keepup_db import tables
+
+#: The names the declarations came with, kept beside them.
+MODULES_TABLE = "frontend_modules"
+ROLE_MODULES_TABLE = "role_modules"
+PLUGIN_OVERRIDES_TABLE = "plugin_overrides"
+
+__all__ = ["FRONTEND_MODULES", "PLUGIN_OVERRIDES", "ROLE_MODULES"]
+
+FRONTEND_MODULES = tables.table(
+    MODULES_TABLE,
+    tables.auto_id(),
+    Column("module_id", Text, unique=True, nullable=False),
+    Column("name", Text, nullable=False),
+    Column("description", Text),
+    Column("js_path", Text),
+    Column("css_path", Text),
+    Column("init_function", Text),
+    # What the catalogue entry says about how the panel shows the section
+    # (keepup-113): they lived only in sections.json, so a section added from
+    # the panel could not carry a handler, an address or an order.
+    Column("icon", Text),
+    Column("handler_function", Text),
+    Column("route_path", Text),
+    Column("section_id", Text),
+    Column("admin_only", Boolean, server_default=sql_text("FALSE")),
+    Column("nav_order", Integer),
+    # Which plugin -- or which file -- declared this section. What makes
+    # removal and the read-time filter possible.
+    Column("declared_by", Text),
+    Column("version", Text, server_default="1.0.0"),
+    Column("is_active", Boolean, server_default=sql_text("TRUE")),
+    Column("config", Text),
+    Column("created_at", DateTime, server_default=tables.NOW),
+    Column("updated_at", DateTime, server_default=tables.NOW),
+    Index("idx_frontend_modules_active", "is_active"),
+)
+
+ROLE_MODULES = tables.table(
+    ROLE_MODULES_TABLE,
+    tables.auto_id(),
+    Column("role_name", Text, nullable=False),
+    Column("module_id", Text, nullable=False),
+    Column("is_active", Boolean, server_default=sql_text("TRUE")),
+    Column("created_at", DateTime, server_default=tables.NOW),
+    UniqueConstraint("role_name", "module_id"),
+    Index("idx_role_modules_role", "role_name"),
+    Index("idx_role_modules_active", "is_active"),
+)
+
+#: Which backend plugins an administrator switched on or off, by stand (task 65).
+#: The file `config/modules.json` stays the seed: it is committed and shared
+#: between deployments, so a decision about one stand belongs in that stand's
+#: own database. Read at start-up by `keepup.plugins.enablement`; the
+#: environment still overrules it.
+PLUGIN_OVERRIDES = tables.table(
+    PLUGIN_OVERRIDES_TABLE,
+    Column("plugin_id", Text, primary_key=True, nullable=True),
+    Column("enabled", Boolean, nullable=False),
+    Column("changed_by", Integer),
+    Column("changed_at", DateTime, server_default=tables.NOW),
+)

keepup_modules-0.5.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: keepup-modules
+Version: 0.5.0
+Summary: The catalogue of panel sections, and the decision about backend plugins.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: keepup-admin>=0.4.0
+Requires-Dist: keepup-db>=0.4.0
+Requires-Dist: keepup-users>=0.4.0
+Requires-Dist: keepup-auth>=0.4.0
+Requires-Dist: fastapi<1,>=0.128
+Requires-Dist: pydantic<3,>=2.11
+
+# keepup-modules
+
+The catalogue of panel sections, and the decision about backend plugins.
+
+One capability of [keepup](https://github.com/FedorSergeev/keepup-admin), the framework over FastAPI for admin
+panels: the base is installed as `keepup-admin` and imported as `keepup`, and
+this distribution carries one part of it. It is installed on its own
+(`pip install keepup-modules`) or together with the base (`pip install "keepup-admin[panel]"`),
+and it declares itself to the kernel through its
+`[project.entry-points."keepup.plugins"]` entry point.

keepup_modules-0.5.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+keepup_modules/__init__.py,sha256=jP8WvPP5oi07OMscW4NK0PJhbbYmweVH_1v6OV1TBtA,1460
+keepup_modules/catalogue.py,sha256=qKcqD3gqXTFkKXY3tSeREwJvzxMSV_WHByTLPm7jRqg,34909
+keepup_modules/decisions.py,sha256=POGGDt2oPWUVHG94F2zmuKY0CpgS-oSlHSjjUU-XvRs,12996
+keepup_modules/plugin.py,sha256=sGYwEKCOE_F7JGRcyaPaSjfcNKniX8nuN1zkzAuOEbY,5508
+keepup_modules/tables.py,sha256=V0_fT4On5k9XAL7gpTev3P2wS6YAncCHA-ZSQhFZud8,3459
+keepup_modules-0.5.0.dist-info/METADATA,sha256=YC6l66gvnST46J6uEbpCQQAlT0GSCKk5XkQf6w2rZJA,957
+keepup_modules-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+keepup_modules-0.5.0.dist-info/entry_points.txt,sha256=Q9G8GKQgRE_On0zqk_oEpYYrxTSaMWUuX_2nWzeOXKE,56
+keepup_modules-0.5.0.dist-info/top_level.txt,sha256=rVSSTZQLLqP_XNO0I8k-Ymmgc-82B0gkJ64mvgR1iDk,15
+keepup_modules-0.5.0.dist-info/RECORD,,

keepup_modules-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

keepup_modules-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[keepup.plugins]
+modules = keepup_modules:ModulesPlugin

keepup_modules-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+keepup_modules