graphddb-runtime 0.2.4__tar.gz → 0.2.5__tar.gz

{graphddb_runtime-0.2.4 → graphddb_runtime-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.2.4
+Version: 0.2.5
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9

{graphddb_runtime-0.2.4 → graphddb_runtime-0.2.5}/graphddb_runtime/__init__.py

@@ -31,12 +31,31 @@ from .per_key_cursor import (
     encode_per_key_cursor,
     serialize_contract_key,
 )
+from .middleware import (
+    MiddlewareRegistry,
+    MiddlewareRuntime,
+    PersistCtx,
+    ReadOpCtx,
+    ReadRequestCtx,
+    RECOVER_NONE,
+    WriteCtx,
+    WriteRuntime,
+)
 from .runtime import GraphDDBRuntime
 
 __all__ = [
     "GraphDDBRuntime",
     "AsyncGraphDDBRuntime",
     "RuntimeLimits",
+    # middleware / hooks (issue #50 / #140 — Python parity)
+    "MiddlewareRegistry",
+    "MiddlewareRuntime",
+    "WriteRuntime",
+    "ReadRequestCtx",
+    "ReadOpCtx",
+    "WriteCtx",
+    "PersistCtx",
+    "RECOVER_NONE",
     "RELATION_TRAVERSAL_CONCURRENCY",
     "map_with_concurrency",
     "GraphDDBError",

{graphddb_runtime-0.2.4 → graphddb_runtime-0.2.5}/graphddb_runtime/async_runtime.py

@@ -43,6 +43,18 @@ class AsyncGraphDDBRuntime:
     def __init__(self, runtime: GraphDDBRuntime) -> None:
         self.sync = runtime
 
+    def use(self, mw: Any) -> None:
+        """Register a host-side middleware on the wrapped runtime (issue #140).
+
+        Middleware is host-only config (never serialized); registering it on the
+        shared sync runtime means an ``async`` caller and a ``sync`` caller of the
+        same runtime see the identical hook chain."""
+        self.sync.use(mw)
+
+    def clear_middleware(self) -> None:
+        """Remove every registered middleware on the wrapped runtime."""
+        self.sync.clear_middleware()
+
     async def execute_query(
         self,
         query_id: str,
@@ -99,9 +111,10 @@ class AsyncGraphDDBRuntime:
         self,
         transaction_id: str,
         params: Mapping[str, Any],
+        options: Optional[Mapping[str, Any]] = None,
     ) -> None:
         await asyncio.to_thread(
-            self.sync.execute_transaction, transaction_id, params
+            self.sync.execute_transaction, transaction_id, params, options
         )
 
     async def explain(self, query_id: str, params: Mapping[str, Any]) -> dict:

graphddb_runtime-0.2.5/graphddb_runtime/middleware.py

@@ -0,0 +1,485 @@
+"""Host-side middleware / hooks for the Python runtime (issue #50, #140).
+
+The Python runtime parity counterpart of the TypeScript ``src/middleware/``. It
+implements the SAME hook points as the TS reference — read R1–R5 and write
+W1–W5 — with the SAME interface (a ``Middleware`` carrying optional ``read`` /
+``write`` hook groups), the SAME ``context`` injection per call, the SAME
+ordering (``before*`` first-registered-first / FIFO; ``after*`` and ``on_error``
+last-registered-first / LIFO), and the SAME atomicity (a transaction
+``before``-throw aborts the whole transaction; the persist hooks fire once per
+atomic batch; ``on_error`` may recover by returning a value).
+
+This is a **parallel, host-only** implementation. Like the TS hooks, a
+``Middleware`` is NEVER serialized: it lives only on the runtime's host-side
+:class:`MiddlewareRegistry` (the Python equivalent of the TS ``ClientManager``)
+and never touches ``operations.json`` / the planner / the spec generator, so the
+TS↔Python bridge (#48) is unaffected.
+
+Idiomatic Python differences from the TS reference (behavior is identical):
+
+- The runtime core is synchronous (boto3 is sync), so hooks are plain callables
+  invoked synchronously rather than ``await``ed. The :class:`AsyncGraphDDBRuntime`
+  wrapper runs the whole sync call (hooks included) in a worker thread, so an
+  ``async`` caller sees the identical behavior without a second hook path.
+- Hook groups are expressed as nested ``dict`` / mapping (``{"read": {"op":
+  {...}}}``) OR a small object with the matching attributes — a ``Middleware``
+  is anything :func:`_hook` can read a callable off. This mirrors the TS object
+  literal a host registers, and keeps registration as light as ``runtime.use({...})``.
+- Context objects are mutable dataclasses; the mutable fields the proposal marks
+  (``params`` in R1, ``operation`` in R2, ``kind`` / ``input`` in W1, ``items``
+  in W3) are plain attributes a hook reassigns or mutates in place.
+
+A read or write issued with no ``context`` sees an empty ``{}`` — exactly as the
+TS runtime threads ``context ?? {}``.
+
+@see docs/proposals/read-middleware.md
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    Tuple,
+)
+
+# A registered middleware is any object/mapping carrying the hook groups. The
+# library never validates its shape beyond reading callables off the known
+# paths, mirroring the TS "hooks are unrestricted" stance (proposal appendix A).
+Middleware = Any
+RequestContext = Dict[str, Any]
+Item = Dict[str, Any]
+
+
+# ── hook lookup ─────────────────────────────────────────────────────────────
+
+
+def _branch(node: Any, key: str) -> Any:
+    """Read a sub-group (``read`` / ``write`` / ``op`` / ``persist``) off a node.
+
+    A node is either a mapping (the common ``{...}`` registration literal) or an
+    object with attributes; either form is supported so a host may register a
+    dict OR a small class instance — both are idiomatic Python.
+    """
+    if node is None:
+        return None
+    if isinstance(node, Mapping):
+        return node.get(key)
+    return getattr(node, key, None)
+
+
+def _hook(mw: Middleware, *path: str) -> Optional[Callable[..., Any]]:
+    """Resolve the callable at ``path`` (e.g. ``"read", "op", "before"``), or None.
+
+    Returns ``None`` when any segment is absent or the leaf is not callable, so an
+    unset hook is simply skipped (matching the TS ``if (hook) ...`` guards).
+    """
+    node: Any = mw
+    for segment in path:
+        node = _branch(node, segment)
+        if node is None:
+            return None
+    return node if callable(node) else None
+
+
+# ── registry ────────────────────────────────────────────────────────────────
+
+
+class MiddlewareRegistry:
+    """A process/runtime-scoped, registration-ordered list of middleware.
+
+    Mirrors the TS ``MiddlewareRegistry`` on ``ClientManager``: append-only via
+    :meth:`use`, cleared via :meth:`clear`, snapshotted per call via
+    :meth:`snapshot` so a call's hook set is stable even if middleware is
+    registered / cleared mid-flight.
+    """
+
+    def __init__(self) -> None:
+        self._list: List[Middleware] = []
+
+    def use(self, mw: Middleware) -> None:
+        """Register a middleware (appended last → runs last in FIFO ``before*``)."""
+        self._list.append(mw)
+
+    def clear(self) -> None:
+        """Remove all registered middleware (teardown / tests)."""
+        self._list = []
+
+    def snapshot(self) -> Tuple[Middleware, ...]:
+        """A point-in-time, registration-ordered snapshot."""
+        return tuple(self._list)
+
+
+# ── context objects ───────────────────────────────────────────────────────────
+
+
+@dataclass
+class ReadRequestCtx:
+    """R1 / R4 / R5 (request-level) context.
+
+    ``before`` (R1) may mutate :attr:`params` and may raise to cancel; ``after``
+    (R4) receives the final assembled result and may return a replacement;
+    ``on_error`` (R5) sees a request-level failure and may recover by returning a
+    value.
+    """
+
+    kind: str  # 'query'
+    model: Any
+    context: RequestContext
+    params: Dict[str, Any]
+    state: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ReadOpCtx:
+    """R2 / R3 / R5 (op-level) context — fires for the root read AND every relation
+    fan-out fetch (incl. nested recursion).
+
+    ``before`` (R2) may mutate :attr:`operation` before it is sent and may raise
+    to cancel; ``after`` (R3) receives the op's raw items and may return a
+    replacement list; ``on_error`` (R5) sees the op-level failure and may recover
+    by returning an item list.
+    """
+
+    kind: str  # 'GetItem' | 'Query' | 'BatchGetItem'
+    model: Any
+    context: RequestContext
+    operation: Dict[str, Any]
+    relation_path: Tuple[str, ...]
+    state: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class WriteCtx:
+    """W1 / W2 / W5 (logical-write-level) context.
+
+    ``before`` (W1) may mutate :attr:`kind` and :attr:`input` (incl. the
+    delete→update soft-delete rewrite) and may raise to cancel (in a transaction,
+    aborting ALL ops); ``after`` (W2) observes the committed change; ``on_error``
+    (W5) sees the logical-level failure and may recover by returning a value.
+    """
+
+    kind: str  # 'put' | 'update' | 'delete'
+    model: Any
+    context: RequestContext
+    input: Dict[str, Any]
+    state: Dict[str, Any] = field(default_factory=dict)
+    transaction: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class PersistCtx:
+    """W3 / W4 / W5 (physical-persist-level) context — fires AFTER derivation, on
+    the REAL composed batch.
+
+    ``before`` (W3) may mutate :attr:`items` (the fully composed Put / Update /
+    Delete / ConditionCheck set) and may raise to abort the batch; ``after`` (W4)
+    observes the executor results; ``on_error`` (W5) sees the persist-level
+    failure and may recover by returning a value.
+
+    In a transaction the persist hooks fire ONCE for the whole atomic batch; for a
+    single-op write :attr:`items` is a one-element list.
+    """
+
+    items: List[Dict[str, Any]]
+    origins: Tuple[Dict[str, Any], ...]
+    context: RequestContext
+    state: Dict[str, Any] = field(default_factory=dict)
+    transaction: Optional[Dict[str, Any]] = None
+
+
+# A sentinel distinguishing "an on_error hook declined" (returned None) from "an
+# on_error hook recovered with the value None". TS uses `!== undefined`; Python's
+# only spare in-band value is a private sentinel, so a hook that genuinely wants
+# to recover with `None` returns this. A bare `None` (the common "decline")
+# means "did not recover".
+class _Decline:
+    __slots__ = ()
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return "<decline>"
+
+
+# Recover-with-None marker the host returns to recover a read/write to the value
+# ``None`` (e.g. a ``query`` recovering to "no row"). Returning a bare ``None``
+# means decline (the original error rethrows).
+RECOVER_NONE = object()
+
+
+def _recovered(value: Any) -> Tuple[bool, Any]:
+    """Interpret an ``on_error`` hook return as (did_recover, value).
+
+    - a bare ``None`` → declined (did NOT recover);
+    - :data:`RECOVER_NONE` → recovered with the value ``None``;
+    - any other value → recovered with that value.
+    """
+    if value is None:
+        return False, None
+    if value is RECOVER_NONE:
+        return True, None
+    return True, value
+
+
+# ── read runtime ───────────────────────────────────────────────────────────────
+
+
+class MiddlewareRuntime:
+    """The per-read middleware runtime — the read-path counterpart of the TS
+    ``MiddlewareRuntime``.
+
+    Immutable wrt the middleware list and the request ``context``; built ONCE at
+    the request entry (R1) and threaded by reference into the root read and every
+    relation fan-out op so a read's hook set is stable for its whole life.
+    """
+
+    def __init__(self, chain: Sequence[Middleware], context: RequestContext) -> None:
+        self._chain: Tuple[Middleware, ...] = tuple(chain)
+        self.context = context
+
+    @property
+    def active(self) -> bool:
+        """``True`` when at least one middleware is registered for this read."""
+        return len(self._chain) > 0
+
+    def request_ctx(
+        self, kind: str, model: Any, params: Dict[str, Any]
+    ) -> ReadRequestCtx:
+        """Build the request-level context (R1 / R4 / R5 share it). Pure."""
+        return ReadRequestCtx(kind=kind, model=model, context=self.context, params=params)
+
+    def run_request_before(self, ctx: ReadRequestCtx) -> None:
+        """R1 — request entry, before key-resolution / plan. Runs every
+        ``read.before`` FIFO; a hook may mutate ``ctx.params`` and may raise to
+        cancel the read."""
+        for mw in self._chain:
+            hook = _hook(mw, "read", "before")
+            if hook is not None:
+                hook(ctx)
+
+    def run_request_after(self, ctx: ReadRequestCtx, result: Any) -> Any:
+        """R4 — final assembled, relation-merged result. Runs every
+        ``read.afterFetch`` LIFO, threading each hook's return into the next
+        (onion), and returns the final (possibly replaced) result."""
+        current = result
+        for mw in reversed(self._chain):
+            hook = _hook(mw, "read", "afterFetch")
+            if hook is not None:
+                current = hook(ctx, current)
+        return current
+
+    def run_request_error(self, ctx: ReadRequestCtx, err: BaseException) -> Any:
+        """R5 (request-level) — runs every ``read.onError`` LIFO. A hook may
+        recover by RETURNING a value (the first such hook wins and short-circuits);
+        otherwise the original error rethrows."""
+        for mw in reversed(self._chain):
+            hook = _hook(mw, "read", "onError")
+            if hook is None:
+                continue
+            did, value = _recovered(hook(ctx, err))
+            if did:
+                return value
+        raise err
+
+    def run_op(
+        self,
+        operation: Dict[str, Any],
+        relation_path: Tuple[str, ...],
+        model: Any,
+        send: Callable[[Dict[str, Any]], List[Item]],
+    ) -> List[Item]:
+        """Drive ONE physical op (root read or any fan-out fetch) through R2 → send
+        → R3, with R5 (op-level) on failure.
+
+        1. R2 (``read.op.before``, FIFO) — may mutate ``ctx.operation``, may raise;
+        2. the caller's ``send`` runs against the (possibly mutated) operation;
+        3. R3 (``read.op.afterFetch``, LIFO) — transforms the raw items (onion);
+        4. on any raise, R5 (``read.op.onError``, LIFO) runs: a hook may recover by
+           RETURNING an item list (those become this op's items); else rethrow.
+
+        ``send`` receives ``ctx.operation`` so a caller that sends what this passes
+        through observes an R2 mutation on the actual send.
+        """
+        ctx = ReadOpCtx(
+            kind=_op_kind(operation),
+            model=model,
+            context=self.context,
+            operation=operation,
+            relation_path=relation_path,
+        )
+        try:
+            for mw in self._chain:
+                hook = _hook(mw, "read", "op", "before")
+                if hook is not None:
+                    hook(ctx)
+            items = send(ctx.operation)
+            for mw in reversed(self._chain):
+                hook = _hook(mw, "read", "op", "afterFetch")
+                if hook is not None:
+                    items = hook(ctx, items)
+            return items
+        except BaseException as err:  # noqa: BLE001 - mirrors TS catch-all
+            for mw in reversed(self._chain):
+                hook = _hook(mw, "read", "op", "onError")
+                if hook is None:
+                    continue
+                did, value = _recovered(hook(ctx, err))
+                if did:
+                    return value if value is not None else []
+            raise
+
+
+def _op_kind(operation: Mapping[str, Any]) -> str:
+    """Map a physical operation to the R2/R3 op kind (its ``type``)."""
+    return operation.get("type", "")
+
+
+# ── write runtime ──────────────────────────────────────────────────────────────
+
+
+class WriteRuntime:
+    """The per-write middleware runtime — the write-path counterpart of the TS
+    ``WriteRuntime``.
+
+    Built ONCE per logical write call (single-op) or per transaction (the persist
+    hooks fire once for the whole atomic batch). Drives W1–W5 with the SAME
+    ordering: ``before*`` FIFO; ``after`` / ``on_error`` LIFO.
+    """
+
+    def __init__(self, chain: Sequence[Middleware], context: RequestContext) -> None:
+        self._chain: Tuple[Middleware, ...] = tuple(chain)
+        self.context = context
+
+    @property
+    def active(self) -> bool:
+        """``True`` when at least one middleware is registered for this write."""
+        return len(self._chain) > 0
+
+    @property
+    def has_write_after(self) -> bool:
+        """``True`` when at least one registered middleware sets a ``write.after``
+        (W2) hook.
+
+        The single-op write path uses this to decide whether to request the
+        pre-write image (``ReturnValues: ALL_OLD``) so W2 receives a real
+        ``{ oldImage, newImage }`` rather than ``{}`` — the cost is paid only when
+        a W2 hook actually exists (parity with the TS ``WriteRuntime.hasWriteAfter``).
+        """
+        return any(_hook(mw, "write", "after") is not None for mw in self._chain)
+
+    def write_ctx(
+        self,
+        kind: str,
+        model: Any,
+        write_input: Dict[str, Any],
+        transaction: Optional[Dict[str, Any]] = None,
+    ) -> WriteCtx:
+        """Build a W1/W2/W5 logical-write context (pure). ``transaction`` is set
+        when the op is part of an atomic batch."""
+        return WriteCtx(
+            kind=kind,
+            model=model,
+            context=self.context,
+            input=write_input,
+            transaction=transaction,
+        )
+
+    def run_write_before(self, ctx: WriteCtx) -> None:
+        """W1 — logical write, before effect derivation. Runs every
+        ``write.before`` FIFO; a hook may mutate ``ctx.kind`` / ``ctx.input``
+        (incl. the delete→update rewrite) and may raise to cancel (in a tx, the
+        raise propagates and aborts the whole batch)."""
+        for mw in self._chain:
+            hook = _hook(mw, "write", "before")
+            if hook is not None:
+                hook(ctx)
+
+    def run_write_after(self, ctx: WriteCtx, change: Mapping[str, Any]) -> None:
+        """W2 — logical write, after commit. Runs every ``write.after`` LIFO with
+        the committed change. Observe-only."""
+        for mw in reversed(self._chain):
+            hook = _hook(mw, "write", "after")
+            if hook is not None:
+                hook(ctx, change)
+
+    def run_write_error(self, ctx: WriteCtx, err: BaseException) -> Tuple[bool, Any]:
+        """W5 (logical-level) — runs every ``write.onError`` LIFO. Returns
+        ``(did_recover, value)``; the first hook that recovers wins. If none
+        recovers, the original error rethrows (symmetric with the read
+        ``onError``)."""
+        for mw in reversed(self._chain):
+            hook = _hook(mw, "write", "onError")
+            if hook is None:
+                continue
+            did, value = _recovered(hook(ctx, err))
+            if did:
+                return True, value
+        raise err
+
+    def persist_ctx(
+        self,
+        items: List[Dict[str, Any]],
+        origins: Sequence[Mapping[str, Any]],
+        transaction: Optional[Dict[str, Any]] = None,
+    ) -> PersistCtx:
+        """Build a W3/W4/W5 persist context (pure)."""
+        return PersistCtx(
+            items=items,
+            origins=tuple(origins),
+            context=self.context,
+            transaction=transaction,
+        )
+
+    def run_persist(
+        self,
+        ctx: PersistCtx,
+        send: Callable[[List[Dict[str, Any]]], Any],
+    ) -> Any:
+        """Drive the PHYSICAL persist of one composed batch through W3 → send → W4,
+        with W5 (persist-level) on failure.
+
+        1. W3 (``write.persist.before``, FIFO) — may mutate ``ctx.items``, may raise;
+        2. the caller's ``send`` runs against the (possibly mutated) ``ctx.items``;
+        3. W4 (``write.persist.after``, LIFO) — observes the executor results;
+        4. on any raise, W5 (``write.persist.onError``, LIFO) runs: a hook may
+           recover by returning a value (treated as the send's result; W4 still
+           runs with it). If none recovers, the original error rethrows.
+        """
+        try:
+            for mw in self._chain:
+                hook = _hook(mw, "write", "persist", "before")
+                if hook is not None:
+                    hook(ctx)
+            results = send(ctx.items)
+        except BaseException as err:  # noqa: BLE001 - mirrors TS catch-all
+            recovered_value: Any = None
+            did_recover = False
+            for mw in reversed(self._chain):
+                hook = _hook(mw, "write", "persist", "onError")
+                if hook is None:
+                    continue
+                did, value = _recovered(hook(ctx, err))
+                if did:
+                    recovered_value = value
+                    did_recover = True
+                    break
+            if not did_recover:
+                raise
+            results = recovered_value
+        for mw in reversed(self._chain):
+            hook = _hook(mw, "write", "persist", "after")
+            if hook is not None:
+                hook(ctx, results)
+        return results
+
+
+# The shared EMPTY runtimes — no middleware, ``active`` is ``False``. Used as the
+# default when a call carries no registered middleware so callers never need a
+# null check; ``run_op`` / ``run_persist`` simply invoke ``send``.
+NO_MIDDLEWARE = MiddlewareRuntime((), {})
+NO_WRITE_MIDDLEWARE = WriteRuntime((), {})