celerp 2.3.4__tar.gz → 2.3.5__tar.gz

{celerp-2.3.4 → celerp-2.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celerp
-Version: 2.3.4
+Version: 2.3.5
 Summary: Free, self-hosted ERP for small businesses
 License: Business Source License 1.1
         

celerp-2.3.5/celerp/capacity.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2026 Noah Severs
+# SPDX-License-Identifier: BUSL-1.1
+"""Request-capacity constants shared by the API pool and the local UI transport.
+
+The app launches one uvicorn worker (both `celerp start` and the Electron shell
+run `uvicorn celerp.main:app` without `--workers`), so one API process owns one
+request connection pool. These constants are the single source of truth for that
+pool's size and for how many connections the web UI is allowed to open into that
+process, so the two can never drift apart. The base size is the interactive
+ceiling; the overflow is held back for background work, relay, auth, and bursts.
+
+This module has no side effects and imports nothing from the app, so both the
+database engine and the UI transport can read it without an import cycle.
+"""
+from __future__ import annotations
+
+# Base connections the single API request pool keeps open, and the extra it may
+# open under burst before refusing. The web UI's interactive transport uses the
+# base size as its own connection ceiling, so a page fan-out can never demand
+# more connections than the pool holds for interactive work.
+REQUEST_DB_POOL_SIZE = 10
+REQUEST_DB_MAX_OVERFLOW = 5

{celerp-2.3.4 → celerp-2.3.5}/celerp/db.py

@@ -9,6 +9,7 @@ from sqlalchemy import text as _sql_text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.pool import NullPool
 
+from celerp.capacity import REQUEST_DB_MAX_OVERFLOW, REQUEST_DB_POOL_SIZE
 from celerp.config import settings
 
 # Shared advisory-lock key that serialises schema migrations across every process
@@ -33,11 +34,13 @@ def mask_db_credentials(text: str) -> str:
 _REQUEST_LOCK_TIMEOUT_MS = "3000"
 _REQUEST_STATEMENT_TIMEOUT_MS = "30000"
 
-# Pool budget: total_possible = (api_workers * (pool_size + max_overflow))
-#                              + (gui_workers * (gui_pool_size + gui_max_overflow))
-# Default workers 2 API + 1 GUI → 2*(10+5) + 1*(5+5) = 40 connections max.
-# Postgres default max_connections=100 leaves 60 for migrations, admin tools, etc.
-# If you increase worker counts, recalculate this budget before deploying.
+# Pool budget: the app runs one API worker (both `celerp start` and the Electron
+# shell launch uvicorn without --workers), so this single process owns one request
+# pool of REQUEST_DB_POOL_SIZE base connections plus REQUEST_DB_MAX_OVERFLOW under
+# burst. The base size is also the web UI's interactive connection ceiling, kept in
+# lockstep through celerp.capacity so the two never drift. Postgres default
+# max_connections=100 leaves ample headroom for migrations, admin tools, and
+# background jobs beyond this pool.
 if os.environ.get("CELERP_TEST_NULLPOOL"):
     # Test mode: a fresh connection per use that closes on return, so a failed
     # test can't leave a poisoned/locked connection lingering in a pooled
@@ -49,8 +52,8 @@ else:
         settings.database_url,
         future=True,
         pool_pre_ping=True,
-        pool_size=10,
-        max_overflow=5,
+        pool_size=REQUEST_DB_POOL_SIZE,
+        max_overflow=REQUEST_DB_MAX_OVERFLOW,
         # Bound how long any query may wait on a lock or run, so a stuck query is
         # cancelled instead of pinning one of the few pooled connections for the
         # full request lifetime (lock_timeout 3s, statement_timeout 30s, in ms).

{celerp-2.3.4 → celerp-2.3.5}/celerp/main.py

@@ -26,6 +26,7 @@ from fastapi.staticfiles import StaticFiles
 from celerp.routers import auth, companies, ledger
 from celerp.routers import health, notifications, system, events as events_router_mod
 from celerp.routers import stars as stars_router_mod
+from celerp.routers import search as search_router_mod
 
 import celerp.models  # noqa: F401 - ensures kernel models (UserCompany, ImportBatch, DocShareToken) are registered
 
@@ -466,6 +467,7 @@ app.include_router(system.router, prefix="/system", tags=["system"])
 app.include_router(stars_router_mod.router, prefix="/stars", tags=["stars"])
 app.include_router(notifications.router)
 app.include_router(events_router_mod.router)
+app.include_router(search_router_mod.router, tags=["search"])
 
 # Backup router — always registered; individual endpoints gate on cloud connection.
 # celerp_backup lives in default_modules/celerp-backup/ which is not on sys.path

{celerp-2.3.4 → celerp-2.3.5}/celerp/modules/loader.py

@@ -35,6 +35,7 @@ import functools
 import hashlib
 import importlib
 import importlib.util
+import inspect
 import json
 import logging
 import os
@@ -45,7 +46,7 @@ from pathlib import Path
 from celerp.modules.importer import PREMIUM_MARKER
 from celerp.modules.license import check_license, exchange_api_key_for_jwt, is_premium_path
 from celerp.modules.meta import META_FILENAME
-from celerp.modules.slots import register as register_slot
+from celerp.modules.slots import register as register_slot, resolve_handler
 from celerp.services.permissions import is_permission_key
 
 log = logging.getLogger(__name__)
@@ -808,10 +809,16 @@ def _load_one(pkg_path: Path, pkg_name: str, *, trusted: bool = False) -> dict |
                 f"  {_MODULE_AI_API_URL}"
             )
 
+    slots_manifest = manifest.get("slots") or {}
+
     # A slot item naming a permission key outside the registry would KeyError in
     # the sidebar builder on every page render, taking the whole UI down for
-    # every user. Refuse the module here, with the bad key named, instead.
-    for slot_name, contribution in (manifest.get("slots") or {}).items():
+    # every user. Refuse the module here, with the bad key named, instead. The
+    # search_provider slot has its own stricter validation below (which also
+    # checks its permission), so it is skipped here.
+    for slot_name, contribution in slots_manifest.items():
+        if slot_name == _SEARCH_PROVIDER_SLOT:
+            continue
         items = contribution if isinstance(contribution, list) else [contribution]
         for item in items:
             perm = item.get("permission") if isinstance(item, dict) else None
@@ -829,14 +836,38 @@ def _load_one(pkg_path: Path, pkg_name: str, *, trusted: bool = False) -> dict |
                     f"closest existing key."
                 )
 
-    # Register extension slots
-    for slot_name, contribution in (manifest.get("slots") or {}).items():
+    # Validate the search_provider descriptor and resolve its handler BEFORE any
+    # slot is registered, so a broken provider rejects the whole module cleanly
+    # (no half-registered slots) rather than first surfacing as a degraded source
+    # when a user types into search.
+    prepared_search_provider = None
+    if _SEARCH_PROVIDER_SLOT in slots_manifest:
+        try:
+            prepared_search_provider = _prepare_search_provider(
+                pkg_name, pkg_path, slots_manifest[_SEARCH_PROVIDER_SLOT],
+                trusted=trusted,
+            )
+        except ModuleLoadError:
+            log.error("Module %r rejected: invalid search_provider slot", pkg_name)
+            for key in list(sys.modules.keys()):
+                if key == pkg_name or key.startswith(pkg_name + "."):
+                    sys.modules.pop(key, None)
+            raise
+
+    # Register extension slots (search_provider is registered from its prepared
+    # descriptor below, never through the generic path).
+    for slot_name, contribution in slots_manifest.items():
+        if slot_name == _SEARCH_PROVIDER_SLOT:
+            continue
         if isinstance(contribution, dict):
             register_slot(slot_name, {**contribution, "_module": pkg_name})
         elif isinstance(contribution, list):
             for item in contribution:
                 register_slot(slot_name, {**item, "_module": pkg_name})
 
+    if prepared_search_provider is not None:
+        register_slot(_SEARCH_PROVIDER_SLOT, prepared_search_provider)
+
     # Register module-contributed UI translation catalogs (the `locales`
     # manifest key, mirroring `slots` above). Each entry maps a language code to
     # {"file": <path>, "rtl": <bool>}. Pushed into ui.i18n through a lazy import
@@ -1004,6 +1035,31 @@ def _flag_dynamic_import(node: ast.Call, violations: set[str]) -> None:
             violations.add(hit)
 
 
+def _module_source_file(pkg_path: Path, dotted_module_path: str) -> Path | None:
+    """The local ``.py`` (or package ``__init__.py``) inside ``pkg_path`` that a
+    dotted module path names, or None if no such source lives in the installed
+    module tree.
+
+    Handles both the flat layout (``pkg_path`` IS the top-level package, its
+    folder name == the package) and the nested GitHub-style layout (the package
+    sits one level in, at ``pkg_path/<top_pkg>``). Used to prove a search
+    handler's source is owned by the module before core imports it, and to seed
+    the protected-BSL AST scan from that same file.
+    """
+    parts = dotted_module_path.split(".")
+    if not parts or not parts[0]:
+        return None
+    top_pkg = parts[0]
+    pkg_dir = pkg_path if pkg_path.name == top_pkg else pkg_path / top_pkg
+    entry = pkg_dir.joinpath(*parts[1:]).with_suffix(".py")
+    if entry.exists():
+        return entry
+    entry = pkg_dir.joinpath(*parts[1:], "__init__.py")
+    if entry.exists():
+        return entry
+    return None
+
+
 def _ast_scan_module_file(pkg_path: Path, dotted_module_path: str) -> set[str]:
     """Protected-BSL-internal imports reachable from the given entry module.
 
@@ -1038,10 +1094,8 @@ def _ast_scan_module_file(pkg_path: Path, dotted_module_path: str) -> set[str]:
                 return cand
         return None
 
-    entry = pkg_dir.joinpath(*parts[1:]).with_suffix(".py")
-    if not entry.exists():
-        entry = pkg_dir.joinpath(*parts[1:], "__init__.py")
-    if not entry.exists():
+    entry = _module_source_file(pkg_path, dotted_module_path)
+    if entry is None:
         return set()
 
     violations: set[str] = set()
@@ -1084,3 +1138,172 @@ def _ast_scan_module_file(pkg_path: Path, dotted_module_path: str) -> set[str]:
             elif isinstance(node, ast.Call):
                 _flag_dynamic_import(node, violations)
     return violations
+
+
+# The search_provider slot has a stricter contract than the generic slots: a
+# single descriptor (never a list), a closed key set, and a locally-owned async
+# handler resolved at load time. The template linter mirrors these exactly.
+_SEARCH_PROVIDER_SLOT = "search_provider"
+_SEARCH_PROVIDER_KEYS = frozenset({"handler", "result_key", "permission"})
+_SEARCH_RESULT_KEYS = frozenset({"items", "entries"})
+
+
+def _enclosing_first_party_module(source_file: Path, expected_name: str) -> Path | None:
+    """The nearest ancestor directory of ``source_file`` that is a content-verified
+    first-party module folder named ``expected_name``, or None.
+
+    Used to accept a first-party module whose handler resolves to the SAME
+    first-party module already loaded from another location (a shipped default
+    scanned from two roots - e.g. the repo copy and a reseeded copy). is_first_party
+    requires the lock name AND a matching content digest, so a match here is
+    content-identical to the module being loaded; a resolution to core, or to any
+    other module, has no such ancestor and is rejected.
+    """
+    for parent in source_file.parents:
+        if parent.name == expected_name and is_first_party(parent):
+            return parent
+    return None
+
+
+def _handler_source_owned(
+    proof: str | None, pkg_root: str, pkg_name: str, trusted: bool
+) -> bool:
+    """True if a resolved handler/module source file legitimately belongs to the
+    module being loaded.
+
+    It must live under the module's own package root. For a content-verified
+    first-party module ONLY, a source under a different copy of the SAME first-party
+    module (same lock name and verified digest) is also legitimate - the one case
+    where importlib returns an identically-named default already loaded from another
+    root. ``is_relative_to`` returns False for paths on different drives rather than
+    raising, so it needs no cross-drive guard. Never accepts a resolution to core or
+    to a different module, and every untrusted module is held to strict same-tree.
+    """
+    if not proof:
+        return False
+    real = Path(os.path.realpath(proof))
+    if real.is_relative_to(pkg_root):
+        return True
+    if not trusted:
+        return False
+    return _enclosing_first_party_module(real, pkg_name) is not None
+
+
+def _prepare_search_provider(
+    pkg_name: str, pkg_path: Path, contribution, *, trusted: bool
+) -> dict:
+    """Validate a ``search_provider`` descriptor and resolve its handler at load
+    time, returning the runtime descriptor to register.
+
+    The slot takes exactly one dict: one module, one provider, one results
+    bucket, so a module can never overwrite its own search bucket. The descriptor
+    must carry exactly ``{handler, result_key, permission}`` (extra keys are
+    rejected, never ignored, so a misspelling fails loudly); ``result_key`` is one
+    of ``{items, entries}``; ``permission`` is a known key. The handler
+    ``module:function`` must name source that lives inside this module's own tree,
+    must import no protected BSL internal (third-party only), and must resolve at
+    load to an async callable. A provider that cannot pass all of this fails
+    module load rather than first surfacing as a degraded source when a user types
+    into search. Raises :class:`ModuleLoadError` on any violation.
+    """
+    if not isinstance(contribution, dict):
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} takes exactly one descriptor dict, "
+            f"not a {type(contribution).__name__}."
+        )
+    keys = set(contribution)
+    if keys != set(_SEARCH_PROVIDER_KEYS):
+        missing = sorted(_SEARCH_PROVIDER_KEYS - keys)
+        extra = sorted(keys - _SEARCH_PROVIDER_KEYS)
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} descriptor keys must be exactly "
+            f"{sorted(_SEARCH_PROVIDER_KEYS)} (missing={missing}, extra={extra})."
+        )
+    result_key = contribution["result_key"]
+    if result_key not in _SEARCH_RESULT_KEYS:
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} result_key {result_key!r} must be one "
+            f"of {sorted(_SEARCH_RESULT_KEYS)}."
+        )
+    perm = contribution["permission"]
+    if not is_permission_key(perm):
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} names unknown permission key {perm!r}."
+        )
+    handler_path = contribution["handler"]
+    if not isinstance(handler_path, str) or handler_path.count(":") != 1:
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} handler {handler_path!r} must be "
+            f"'module.path:function'."
+        )
+    module_path, func_name = handler_path.split(":", 1)
+    if not module_path or not func_name:
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} handler {handler_path!r} must name a "
+            f"non-empty module path and function."
+        )
+    # Local ownership: the handler must resolve to source inside this module's own
+    # tree, so a manifest can never point core at 'celerp.some_internal:fn' and
+    # have it imported on demand around the protected-import gate.
+    if _module_source_file(pkg_path, module_path) is None:
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} handler {handler_path!r} does not "
+            f"resolve to source inside module {pkg_name!r}."
+        )
+    # The handler is a lazily-imported entry point, so it goes through the same
+    # transitive protected-BSL scan as the route entry modules (third-party only).
+    if not trusted:
+        violations = _ast_scan_module_file(pkg_path, module_path)
+        if violations:
+            raise ModuleLoadError(
+                f"Slot {_SEARCH_PROVIDER_SLOT!r} handler imports protected BSL "
+                f"internals ({', '.join(sorted(violations))})."
+            )
+    try:
+        handler = resolve_handler(handler_path)
+    except Exception as exc:
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} handler {handler_path!r} failed to "
+            f"resolve ({type(exc).__name__})."
+        )
+    if not callable(handler):
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} handler {handler_path!r} is not callable."
+        )
+    if not inspect.iscoroutinefunction(handler):
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} handler {handler_path!r} must be async; "
+            f"the aggregator awaits it."
+        )
+    # Provenance: an on-disk file matching the dotted path is not proof of what
+    # importlib actually resolved. A decoy source shipped inside the module's own
+    # tree (e.g. a celerp/ai/service.py) satisfies the existence and AST checks
+    # above, yet importlib returns the already-loaded REAL core module of the same
+    # dotted name, binding the provider to arbitrary code. Require that BOTH the
+    # resolved module's file AND the handler's own source file be owned by this
+    # module (_handler_source_owned): under its own package root, or - for a
+    # content-verified first-party module only - inside the same first-party module
+    # (same lock name and digest) loaded from another root. realpath collapses
+    # symlinks and '..' so neither can point a proof outside the tree. This runs for
+    # every module: a first-party manifest whose handler resolves to core, or to a
+    # different module, is rejected exactly as an untrusted decoy is.
+    pkg_root = os.path.realpath(pkg_path)
+    try:
+        resolved_module = importlib.import_module(module_path)
+        module_file = getattr(resolved_module, "__file__", None)
+        handler_file = inspect.getsourcefile(inspect.unwrap(handler))
+    except Exception as exc:
+        raise ModuleLoadError(
+            f"Slot {_SEARCH_PROVIDER_SLOT!r} handler {handler_path!r} source could "
+            f"not be located ({type(exc).__name__})."
+        )
+    for proof in (module_file, handler_file):
+        if not _handler_source_owned(proof, pkg_root, pkg_name, trusted):
+            raise ModuleLoadError(
+                f"Slot {_SEARCH_PROVIDER_SLOT!r} handler {handler_path!r} resolves to "
+                f"source outside module {pkg_name!r}'s own package tree."
+            )
+    # Runtime-owned trust metadata is injected AFTER the manifest contribution, and
+    # the closed key set above already rejects a manifest that tries to supply
+    # _module / _first_party itself, so neither can be spoofed.
+    return {**contribution, "_module": pkg_name, "_first_party": trusted}

{celerp-2.3.4 → celerp-2.3.5}/celerp/modules/slots.py

@@ -17,6 +17,14 @@ import_adapter     Source option in the CSV import page
 category_schema    Default field definitions for a named category
 projection_handler Maps event-type prefixes to a handler function
 on_company_created Async callback(session, company_id) fired after a new company is persisted
+search_provider    Contributes rows to the global search bar. Exactly one descriptor
+                   dict per module: {"handler", "result_key", "permission"}. handler
+                   names an in-module "module.path:function" resolved and validated
+                   async at load, invoked as
+                   `async def handler(session, company_id, role, q, limit) -> dict`
+                   returning {result_key: [rows]}; result_key is "items" or "entries";
+                   permission gates the source per company role. See the module loader
+                   for the full descriptor contract.
 
 Usage in core UI
 ----------------
@@ -29,9 +37,26 @@ Usage in core UI
 """
 from __future__ import annotations
 
+from typing import Callable
+
 _slots: dict[str, list[dict]] = {}
 
 
+def resolve_handler(dotted: str) -> Callable:
+    """Resolve a "module.path:function" string to the callable it names.
+
+    Raises ImportError if the module cannot be imported and AttributeError if
+    the module has no such attribute. Callers wrap this in their own try/except
+    to apply their failure policy (swallow, propagate, log-and-skip); the shared
+    resolver never decides that policy, it only does the import and lookup.
+    """
+    import importlib
+
+    module_path, func_name = dotted.rsplit(":", 1)
+    mod = importlib.import_module(module_path)
+    return getattr(mod, func_name)
+
+
 def register(slot: str, contribution: dict) -> None:
     """Register a module contribution into a named slot.
 
@@ -64,7 +89,6 @@ async def fire_lifecycle(slot: str, **kwargs) -> None:
     (with traceback) and swallowed, so a recurrence surfaces as an alert
     instead of vanishing.
     """
-    import importlib
     import logging
 
     _log = logging.getLogger(__name__)
@@ -74,9 +98,7 @@ async def fire_lifecycle(slot: str, **kwargs) -> None:
         if not handler_path:
             continue
         try:
-            mod_path, func_name = handler_path.rsplit(":", 1)
-            mod = importlib.import_module(mod_path)
-            func = getattr(mod, func_name)
+            func = resolve_handler(handler_path)
             await func(**kwargs)
         except Exception as exc:
             _log.exception(
@@ -90,7 +112,6 @@ async def fire_lifecycle_strict(slot_name: str, **kwargs) -> None:
 
     Use for slots where a handler must be able to block the action.
     """
-    import importlib
     import logging
     from fastapi import HTTPException
 
@@ -101,9 +122,7 @@ async def fire_lifecycle_strict(slot_name: str, **kwargs) -> None:
         if not handler_path:
             continue
         try:
-            mod_path, func_name = handler_path.rsplit(":", 1)
-            mod = importlib.import_module(mod_path)
-            func = getattr(mod, func_name)
+            func = resolve_handler(handler_path)
             await func(**kwargs)
         except HTTPException:
             raise

{celerp-2.3.4 → celerp-2.3.5}/celerp/projections/engine.py

@@ -3,7 +3,6 @@
 
 from __future__ import annotations
 
-import importlib
 import logging
 from datetime import datetime, timezone
 
@@ -18,11 +17,15 @@ log = logging.getLogger(__name__)
 
 
 def _resolve_module_handler(dotted: str):
-    """Import and return a handler callable from a 'module.path:function' string."""
+    """Import and return a handler callable from a 'module.path:function' string.
+
+    Returns None on any resolution failure so a single bad projection_handler
+    slot cannot stop the engine from picking up its siblings.
+    """
+    from celerp.modules.slots import resolve_handler
+
     try:
-        module_path, func_name = dotted.rsplit(":", 1)
-        mod = importlib.import_module(module_path)
-        return getattr(mod, func_name)
+        return resolve_handler(dotted)
     except Exception as exc:
         log.error("ProjectionEngine: cannot resolve module handler %r: %s", dotted, exc)
         return None