izana-core 0.1.0__tar.gz → 0.2.0__tar.gz

{izana_core-0.1.0 → izana_core-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: izana-core
-Version: 0.1.0
-Summary: Izana Python core — HMAC cache keys, MWT identity. Framework-agnostic primitives shared by every Python backend adapter.
+Version: 0.2.0
+Summary: Izana Python core — @client registry, dispatch executor, KDL IR, HMAC cache keys, MWT identity. Framework-agnostic primitives shared by every Python backend adapter.
 License-Expression: Elastic-2.0
 Requires-Python: >=3.10
 Requires-Dist: jinja2>=3.1

{izana_core-0.1.0 → izana_core-0.2.0}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "izana-core"
-version = "0.1.0"
+version = "0.2.0"
 license = "Elastic-2.0"
-description = "Izana Python core — HMAC cache keys, MWT identity. Framework-agnostic primitives shared by every Python backend adapter."
+description = "Izana Python core — @client registry, dispatch executor, KDL IR, HMAC cache keys, MWT identity. Framework-agnostic primitives shared by every Python backend adapter."
 requires-python = ">=3.10"
 dependencies = [
     "PyJWT>=2.0",

{izana_core-0.1.0 → izana_core-0.2.0}/src/izana_core/client/function.py

@@ -1,4 +1,3 @@
-
 from __future__ import annotations
 
 import asyncio
@@ -16,7 +15,6 @@ from typing import (
 
 from pydantic import BaseModel
 
-
 # View-path detection needs the framework's response base class, which only
 # the backend adapter registers. While unset, every function is treated as RPC.
 
@@ -89,8 +87,7 @@ class ServerFunction(ABC, Generic[TInput, TOutput]):
         return self.request.user
 
     @abstractmethod
-    def call(self, input: TInput) -> TOutput:
-        ...
+    def call(self, input: TInput) -> TOutput: ...
 
     async def acall(self, input: TInput) -> TOutput:
         return await asyncio.to_thread(self.call, input)
@@ -150,7 +147,9 @@ def _resolve_context(context: ContextMode) -> str | Literal[False]:
         return context.name
     if isinstance(context, str):
         if not context.strip():
-            raise ValueError("context must be a non-empty string, ReactContext, or False.")
+            raise ValueError(
+                "context must be a non-empty string, ReactContext, or False."
+            )
         return context
     raise ValueError(
         f"context must be a ReactContext, a string, or False. Got {type(context).__name__}."
@@ -167,7 +166,7 @@ MergeMode = MergeTarget | list[MergeTarget] | None
 
 
 def client(
-    fn: Callable = None,
+    fn: Callable[..., Any] | None = None,
     *,
     context: ContextMode = False,
     affects: AffectsMode = None,
@@ -179,7 +178,10 @@ def client(
     auth: bool | str | Callable[[Any], bool] | None = None,
     rev: int = 0,
     cache: int | bool = True,
-) -> type[ServerFunction] | Callable[[Callable], type[ServerFunction]]:
+) -> (
+    type[ServerFunction[Any, Any]]
+    | Callable[[Callable[..., Any]], type[ServerFunction[Any, Any]]]
+):
     # Resolve context to name string
     resolved_context = _resolve_context(context)
 
@@ -208,17 +210,33 @@ def client(
 
     def decorator(fn: Callable) -> type[ServerFunction]:
         return _create_server_function(
-            fn, context=resolved_context, affects=affects, merge=merge,
-            private=private, route=route, methods=methods,
-            websocket=websocket, auth=auth, rev=rev, cache=cache,
+            fn,
+            context=resolved_context,
+            affects=affects,
+            merge=merge,
+            private=private,
+            route=route,
+            methods=methods,
+            websocket=websocket,
+            auth=auth,
+            rev=rev,
+            cache=cache,
         )
 
     # Support both @client and @client(...)
     if fn is not None:
         return _create_server_function(
-            fn, context=resolved_context, affects=affects, merge=merge,
-            private=private, route=route, methods=methods,
-            websocket=websocket, auth=auth, rev=rev, cache=cache,
+            fn,
+            context=resolved_context,
+            affects=affects,
+            merge=merge,
+            private=private,
+            route=route,
+            methods=methods,
+            websocket=websocket,
+            auth=auth,
+            rev=rev,
+            cache=cache,
         )
     return decorator
 
@@ -333,7 +351,9 @@ def _create_server_function(
             output_cls = output_type
             is_primitive_output = False
         else:
-            output_cls = create_model(f"{fn.__name__}_Output", result=(output_type, ...))
+            output_cls = create_model(
+                f"{fn.__name__}_Output", result=(output_type, ...)
+            )
             is_primitive_output = True
 
     # Store param names for unpacking validated input

izana_core-0.2.0/src/izana_core/executor.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ValidationError
+from pydantic_core import to_jsonable_python
+
+from izana_core.registry import get_context_groups, get_function
+from izana_core.type_utils import types_match_for_merge
+
+# ─── Error taxonomy ─────────────────────────────────────────────────────────
+#
+# No `status_code` here: HTTP-ness is a transport concern, and only the
+# adapters that have a status line (izana-fastapi) own that table
+# (`status_of` in their router) — a js_api or Tauri-command bridge has no
+# status line at all, so an error carried on the exception itself would be a
+# field every non-HTTP adapter inherits and can never use.
+
+
+class ErrorCode(str, Enum):
+    NOT_FOUND = "NOT_FOUND"
+    BAD_REQUEST = "BAD_REQUEST"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    FORBIDDEN = "FORBIDDEN"
+    NOT_IMPLEMENTED = "NOT_IMPLEMENTED"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+
+class IzanaError(Exception):
+
+    code: ErrorCode = ErrorCode.INTERNAL_ERROR
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+
+
+class NotFound(IzanaError):
+    code = ErrorCode.NOT_FOUND  # noqa: E701
+
+
+class BadRequest(IzanaError):
+    code = ErrorCode.BAD_REQUEST  # noqa: E701
+
+
+class ValidationFailed(IzanaError):
+    code = ErrorCode.VALIDATION_ERROR  # noqa: E701
+
+
+class Unauthorized(IzanaError):
+    code = ErrorCode.UNAUTHORIZED  # noqa: E701
+
+
+class Forbidden(IzanaError):
+    code = ErrorCode.FORBIDDEN  # noqa: E701
+
+
+class NotImplementedYet(IzanaError):
+    code = ErrorCode.NOT_IMPLEMENTED  # noqa: E701
+
+
+class InternalError(IzanaError):
+    code = ErrorCode.INTERNAL_ERROR  # noqa: E701
+
+
+# ─── Auth ───────────────────────────────────────────────────────────────────
+
+
+def _user(request: Any) -> Any:
+    return getattr(getattr(request, "state", None), "user", None)
+
+
+def _is_authenticated(user: Any) -> bool:
+    return bool(user) and getattr(user, "is_authenticated", True)
+
+
+def _enforce_auth(request: Any, requirement: Any) -> None:
+    if requirement is None:
+        return
+
+    user = _user(request)
+
+    match requirement:
+        case True | "required":
+            if not _is_authenticated(user):
+                raise Unauthorized("Authentication required")
+        case "staff":
+            if not _is_authenticated(user):
+                raise Unauthorized("Authentication required")
+            if not getattr(user, "is_staff", False):
+                raise Forbidden("Staff access required")
+        case "superuser":
+            if not _is_authenticated(user):
+                raise Unauthorized("Authentication required")
+            if not getattr(user, "is_superuser", False):
+                raise Forbidden("Superuser access required")
+        case f if callable(f):
+            if not f(request):
+                raise Forbidden("Permission denied")
+        case other:
+            raise InternalError(f"Unknown auth requirement: {other!r}")
+
+
+# ─── Input validation ───────────────────────────────────────────────────────
+
+
+def _validate_input(input_cls: Any, input_data: Any) -> BaseModel | None:
+    if input_cls in (None, BaseModel) or not getattr(input_cls, "model_fields", None):
+        return None
+
+    fields = input_cls.model_fields
+    required = [name for name, f in fields.items() if f.is_required()]
+
+    if not input_data:
+        if required:
+            raise ValidationFailed(
+                "Input validation failed",
+                details={"fields": {name: ["Field required"] for name in required}},
+            )
+        return input_cls()
+
+    if not isinstance(input_data, dict):
+        raise BadRequest(f"Input must be an object, got {type(input_data).__name__}")
+
+    try:
+        return input_cls(**input_data)
+    except ValidationError as e:
+        raise ValidationFailed(
+            "Input validation failed",
+            details={"errors": e.errors()},
+        ) from e
+
+
+# ─── Dispatch ───────────────────────────────────────────────────────────────
+
+
+def _resolve_function(fn_name: str) -> Any:
+    view_class = get_function(fn_name)
+    if view_class is None:
+        raise NotFound("Function not found")
+    if getattr(view_class, "_meta", {}).get("private"):
+        raise Forbidden("Function is not client-callable")
+    return view_class
+
+
+def _serialize(result: Any) -> Any:
+    # A @client Output is always BaseModel / list / dict / enum / primitive,
+    # so pydantic_core's own encoder is total over it — no adapter-specific
+    # recursion needed here.
+    return to_jsonable_python(result)
+
+
+async def execute_function(
+    request: Any,
+    fn_name: str,
+    input_data: dict[str, Any] | None = None,
+) -> Any:
+    view_class = _resolve_function(fn_name)
+    _enforce_auth(request, view_class._meta.get("auth"))
+
+    view = view_class(request)
+    validated = _validate_input(view.Input, input_data)
+
+    try:
+        result = await view.acall(validated)
+    except NotImplementedError as e:
+        raise NotImplementedYet(str(e) or "Not implemented") from e
+    except IzanaError:
+        raise
+    except Exception as e:
+        raise InternalError(str(e)) from e
+
+    return _serialize(result)
+
+
+# ─── Invalidation ───────────────────────────────────────────────────────────
+
+
+def compute_invalidation(
+    view_class: Any, input_data: dict[str, Any] | None
+) -> list[Any]:
+    affects = getattr(view_class, "_meta", {}).get("affects") or []
+    return [_invalidation_target(target, input_data or {}) for target in affects]
+
+
+def compute_merges(
+    view_class: Any, input_data: dict[str, Any] | None, result: Any
+) -> list[dict[str, Any]]:
+    targets = getattr(view_class, "_meta", {}).get("merge") or []
+    if not targets:
+        return []
+    mutation_output = getattr(view_class, "Output", None)
+    out: list[dict[str, Any]] = []
+    for ctx_name in targets:
+        slot = _resolve_merge_slot(ctx_name, mutation_output)
+        if slot is None:
+            continue
+        entry: dict[str, Any] = {"context": ctx_name, "slot": slot, "value": result}
+        scoped = _scoped_params(ctx_name, input_data or {})
+        if scoped:
+            entry["params"] = scoped
+        out.append(entry)
+    return out
+
+
+def _resolve_merge_slot(context_name: str, mutation_output: Any) -> str | None:
+    if mutation_output is None:
+        return None
+    matches: list[str] = []
+    for fn_name in get_context_groups().get(context_name, []):
+        fn_cls = get_function(fn_name)
+        if fn_cls is None:
+            continue
+        fn_output = getattr(fn_cls, "Output", None)
+        if fn_output is not None and types_match_for_merge(fn_output, mutation_output):
+            matches.append(fn_name)
+    return matches[0] if len(matches) == 1 else None
+
+
+def _scoped_params(context_name: str, input_data: dict[str, Any]) -> dict[str, Any]:
+    fn_names = get_context_groups().get(context_name, [])
+    declared: set[str] = set()
+    for fn_name in fn_names:
+        fn_cls = get_function(fn_name)
+        if fn_cls is None:
+            continue
+        input_cls = getattr(fn_cls, "Input", None)
+        if (
+            input_cls
+            and input_cls is not BaseModel
+            and hasattr(input_cls, "model_fields")
+        ):
+            declared.update(input_cls.model_fields.keys())
+    return {k: v for k, v in input_data.items() if k in declared}
+
+
+def _invalidation_target(name: str, input_data: dict[str, Any]) -> Any:
+    scoped = _scoped_params(name, input_data)
+    return {"context": name, "params": scoped} if scoped else name

{izana_core-0.1.0 → izana_core-0.2.0}/src/izana_core/ir.py

@@ -1,4 +1,3 @@
-
 from __future__ import annotations
 
 import re
@@ -18,7 +17,6 @@ from izana_core.registry import (
 )
 from izana_core.type_utils import extract_list_element, extract_optional
 
-
 __all__ = ["build_ir", "wire_to_pascal"]
 
 
@@ -35,7 +33,7 @@ def wire_to_pascal(wire_name: str) -> str:
 def _kdl(value: str) -> str:
     escaped = (
         value.replace("\\", "\\\\")
-        .replace("\"", "\\\"")
+        .replace('"', '\\"')
         .replace("\n", "\\n")
         .replace("\r", "\\r")
         .replace("\t", "\\t")
@@ -315,9 +313,9 @@ _CHANNEL_SLOTS = (
 )
 
 
-def _collect_channels() -> tuple[
-    list[dict[str, Any]], list[tuple[str, type[BaseModel]]]
-]:
+def _collect_channels() -> (
+    tuple[list[dict[str, Any]], list[tuple[str, type[BaseModel]]]]
+):
     channel_classes = get_registry().get("channels", {})
     records: list[dict[str, Any]] = []
     models: list[tuple[str, type[BaseModel]]] = []

izana_core-0.2.0/tests/test_executor.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from pydantic import BaseModel
+
+from izana_core.client.function import client
+from izana_core.executor import (
+    Forbidden,
+    Unauthorized,
+    ValidationFailed,
+    compute_invalidation,
+    compute_merges,
+    execute_function,
+)
+from izana_core.registry import clear_registry, get_function, register
+
+# ─── Fixtures ───────────────────────────────────────────────────────────────
+#
+# Exercised directly against izana_core — no adapter in the loop. An adapter
+# (izana-pywebview, izana-fastapi) only owes a transport over this; the
+# dispatch/auth/validate/serialize/invalidation/merge contract itself is
+# core's, and this is where it's proven independent of any one of them.
+
+
+class EchoOutput(BaseModel):
+    message: str
+
+
+class ItemOutput(BaseModel):
+    id: int
+    name: str
+
+
+class User:
+    def __init__(self, *, is_authenticated: bool, is_staff: bool = False):
+        self.is_authenticated = is_authenticated
+        self.is_staff = is_staff
+
+
+class State:
+    def __init__(self, user: object | None):
+        self.user = user
+
+
+class Req:
+    def __init__(self, user: object | None = None):
+        self.state = State(user)
+
+
+@pytest.fixture
+def registry():
+    clear_registry()
+
+    @client
+    def add(request, a: int, b: int) -> EchoOutput:
+        return EchoOutput(message=f"sum: {a + b}")
+
+    @client(auth=True)
+    def whoami(request) -> EchoOutput:
+        return EchoOutput(message="ok")
+
+    @client(auth="staff")
+    def staff_only(request) -> EchoOutput:
+        return EchoOutput(message="staff ok")
+
+    @client(affects="user")
+    def update_email(request, email: str) -> EchoOutput:
+        return EchoOutput(message=f"updated: {email}")
+
+    @client(merge="items")
+    def set_item_name(request, id: int, name: str) -> ItemOutput:
+        return ItemOutput(id=id, name=name)
+
+    @client(context="items")
+    def items_list(request) -> list[ItemOutput]:
+        return [ItemOutput(id=1, name="orig")]
+
+    register(add, "add")
+    register(whoami, "whoami")
+    register(staff_only, "staff_only")
+    register(update_email, "update_email")
+    register(set_item_name, "set_item_name")
+    register(items_list, "items_list")
+
+    yield None
+
+    clear_registry()
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+# ─── Dispatch + serialize ────────────────────────────────────────────────────
+
+
+class DispatchTests:
+    def test_a_call_dispatches_validates_and_serializes(self, registry):
+        result = run(execute_function(Req(), "add", {"a": 2, "b": 3}))
+        assert result == {"message": "sum: 5"}
+
+    def test_a_list_of_basemodel_serializes_as_a_bare_array(self, registry):
+        result = run(execute_function(Req(), "items_list", {}))
+        assert result == [{"id": 1, "name": "orig"}]
+
+    def test_a_missing_required_field_is_a_validation_failure(self, registry):
+        with pytest.raises(ValidationFailed) as exc:
+            run(execute_function(Req(), "add", {}))
+        assert "a" in exc.value.details["fields"]
+
+
+# ─── Auth ───────────────────────────────────────────────────────────────────
+
+
+class AuthTests:
+    def test_an_unauthenticated_request_to_an_auth_required_function_refuses(
+        self, registry
+    ):
+        with pytest.raises(Unauthorized):
+            run(execute_function(Req(user=None), "whoami", {}))
+
+    def test_an_authenticated_request_passes(self, registry):
+        result = run(
+            execute_function(Req(user=User(is_authenticated=True)), "whoami", {})
+        )
+        assert result == {"message": "ok"}
+
+    def test_a_non_staff_authenticated_user_is_forbidden_from_staff_only(
+        self, registry
+    ):
+        with pytest.raises(Forbidden):
+            run(
+                execute_function(
+                    Req(user=User(is_authenticated=True, is_staff=False)),
+                    "staff_only",
+                    {},
+                )
+            )
+
+
+# ─── Invalidation + merge ────────────────────────────────────────────────────
+
+
+class InvalidationAndMergeTests:
+    def test_affects_computes_the_invalidation_list(self, registry):
+        fn_class = get_function("update_email")
+        assert compute_invalidation(fn_class, {"email": "a@b.com"}) == ["user"]
+
+    def test_merge_computes_a_merge_entry_against_the_matching_context_reader(
+        self, registry
+    ):
+        fn_class = get_function("set_item_name")
+        result = run(execute_function(Req(), "set_item_name", {"id": 1, "name": "x"}))
+        merges = compute_merges(fn_class, {"id": 1, "name": "x"}, result)
+        assert merges == [
+            {"context": "items", "slot": "items_list", "value": {"id": 1, "name": "x"}}
+        ]