graphddb-runtime 0.1.0__py3-none-any.whl

graphddb_runtime/__init__.py

@@ -0,0 +1,58 @@
+"""GraphDDB Python runtime (issue #44, single-operation core).
+
+Public surface consumed by generated ``repositories.py`` and applications:
+
+- :class:`GraphDDBRuntime` — the executor.
+- :class:`RuntimeLimits` — execution-time bounds.
+- the :class:`GraphDDBError` family.
+"""
+
+from __future__ import annotations
+
+from .cursor import decode_cursor, encode_cursor
+from .errors import (
+    CommandNotFoundError,
+    ContractArityError,
+    ContractNotFoundError,
+    GraphDDBError,
+    HydrationError,
+    LimitExceededError,
+    MultiOperationNotSupportedError,
+    OperationExecutionError,
+    ParameterValidationError,
+    QueryNotFoundError,
+    TransactionNotFoundError,
+)
+from .async_runtime import AsyncGraphDDBRuntime
+from .concurrency import RELATION_TRAVERSAL_CONCURRENCY, map_with_concurrency
+from .limits import RuntimeLimits
+from .per_key_cursor import (
+    decode_per_key_cursor,
+    encode_per_key_cursor,
+    serialize_contract_key,
+)
+from .runtime import GraphDDBRuntime
+
+__all__ = [
+    "GraphDDBRuntime",
+    "AsyncGraphDDBRuntime",
+    "RuntimeLimits",
+    "RELATION_TRAVERSAL_CONCURRENCY",
+    "map_with_concurrency",
+    "GraphDDBError",
+    "QueryNotFoundError",
+    "CommandNotFoundError",
+    "TransactionNotFoundError",
+    "ContractNotFoundError",
+    "ContractArityError",
+    "ParameterValidationError",
+    "LimitExceededError",
+    "OperationExecutionError",
+    "HydrationError",
+    "MultiOperationNotSupportedError",
+    "encode_cursor",
+    "decode_cursor",
+    "serialize_contract_key",
+    "encode_per_key_cursor",
+    "decode_per_key_cursor",
+]

graphddb_runtime/async_runtime.py

@@ -0,0 +1,110 @@
+"""Async adapter over the sync :class:`GraphDDBRuntime` (issue #46, Phase 4).
+
+boto3 is a synchronous SDK, so the runtime core is synchronous. This module
+provides a **thin** async wrapper that runs each blocking call in a worker
+thread via :func:`asyncio.to_thread`, giving an ``await``-able surface with
+**behavior equivalent** to the sync runtime (same params, same specs, same
+results, same error types) without duplicating the executor.
+
+It does not require ``aioboto3``; the wrapped sync runtime keeps using boto3.
+For a project that wants a fully non-blocking DynamoDB client, ``aioboto3`` can
+be adopted later behind the same interface — but for the common Lambda / request
+handler case, ``asyncio.to_thread`` is sufficient and keeps a single executor
+implementation (no TS/Python or sync/async divergence to test twice).
+
+Usage::
+
+    import boto3
+    from graphddb_runtime import GraphDDBRuntime, AsyncGraphDDBRuntime
+
+    sync = GraphDDBRuntime(boto3.client("dynamodb"), manifest, operations)
+    runtime = AsyncGraphDDBRuntime(sync)
+
+    user = await runtime.execute_query("getUser", {"userId": "alice"})
+    await runtime.execute_transaction("addManyMembers", {...})
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Mapping, Optional
+
+from .runtime import GraphDDBRuntime
+
+
+class AsyncGraphDDBRuntime:
+    """An ``await``-able adapter delegating to a sync :class:`GraphDDBRuntime`.
+
+    Every method runs its synchronous counterpart in a thread, so a slow boto3
+    round trip does not block the event loop. The wrapped runtime is exposed as
+    :attr:`sync` for callers that need the blocking API directly.
+    """
+
+    def __init__(self, runtime: GraphDDBRuntime) -> None:
+        self.sync = runtime
+
+    async def execute_query(
+        self,
+        query_id: str,
+        params: Mapping[str, Any],
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> Optional[dict]:
+        return await asyncio.to_thread(
+            self.sync.execute_query, query_id, params, options
+        )
+
+    async def execute_query_method(
+        self,
+        contract_name: str,
+        method_name: str,
+        key_or_keys: Any,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        """Async wrapper over :meth:`GraphDDBRuntime.execute_query_method` (#62)."""
+        return await asyncio.to_thread(
+            self.sync.execute_query_method,
+            contract_name,
+            method_name,
+            key_or_keys,
+            params,
+        )
+
+    async def execute_command(
+        self,
+        command_id: str,
+        params: Mapping[str, Any],
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        await asyncio.to_thread(
+            self.sync.execute_command, command_id, params, options
+        )
+
+    async def execute_command_method(
+        self,
+        contract_name: str,
+        method_name: str,
+        key_or_keys: Any,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        """Async wrapper over :meth:`GraphDDBRuntime.execute_command_method` (#64)."""
+        await asyncio.to_thread(
+            self.sync.execute_command_method,
+            contract_name,
+            method_name,
+            key_or_keys,
+            params,
+        )
+
+    async def execute_transaction(
+        self,
+        transaction_id: str,
+        params: Mapping[str, Any],
+    ) -> None:
+        await asyncio.to_thread(
+            self.sync.execute_transaction, transaction_id, params
+        )
+
+    async def explain(self, query_id: str, params: Mapping[str, Any]) -> dict:
+        # `explain` does not touch DynamoDB, but keeping it on the async surface
+        # lets call sites use one runtime object uniformly.
+        return await asyncio.to_thread(self.sync.explain, query_id, params)

graphddb_runtime/batch.py

@@ -0,0 +1,218 @@
+"""BatchGetItem chunking + UnprocessedKeys retry (issue #45).
+
+Port of the TypeScript batch semantics (``src/operations/batch-retry.ts`` /
+``src/executor/batch-executor.ts``):
+
+- keys are **deduped** before the request (``planBatchGetForQueryKeys`` /
+  ``dedupeDynamoKeys``);
+- split into chunks of at most :data:`BATCH_GET_MAX_KEYS` (100) keys;
+- each chunk retries ``UnprocessedKeys`` with exponential backoff
+  (``50 * 2^(attempt-1)`` ms, capped at 1000ms) up to
+  :data:`BATCH_MAX_RETRY_ATTEMPTS` (10) attempts, then raises.
+
+The sleep is injected so unit tests can observe the backoff schedule without
+real delays.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+# Mirrors src/operations/batch-retry.ts.
+BATCH_GET_MAX_KEYS = 100
+BATCH_WRITE_MAX_ITEMS = 25
+BATCH_MAX_RETRY_ATTEMPTS = 10
+
+
+def compute_backoff_delay(attempt: int) -> float:
+    """Backoff for a 1-based attempt: ``50 * 2^(attempt-1)`` ms, capped at 1000ms."""
+    return min(1000.0, 50.0 * (2 ** (attempt - 1))) / 1000.0
+
+
+def chunk(items: List[Any], size: int) -> List[List[Any]]:
+    return [items[i : i + size] for i in range(0, len(items), size)]
+
+
+def serialize_key(key: Mapping[str, Any]) -> str:
+    """Stable string form of a (plain) key for dedup / parent matching.
+
+    Mirrors the TS ``dedupeDynamoKeys`` / ``serializeQueryKey`` ordering
+    (attributes sorted by name).
+    """
+    import json
+
+    return json.dumps(sorted(key.items()), separators=(",", ":"), default=str)
+
+
+class BatchGetExecutor:
+    """Executes a deduped, chunked, retrying BatchGetItem against a boto3 client.
+
+    The client is the low-level ``boto3.client("dynamodb")`` (AttributeValue
+    shapes). ``request_extra`` carries the optional ``ProjectionExpression`` /
+    ``ExpressionAttributeNames``. Returns the flat list of raw (AttributeValue)
+    items across all chunks/retries.
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        *,
+        boto_errors: tuple = (),
+        on_request: Optional[Callable[[int], None]] = None,
+        sleep: Callable[[float], None] = time.sleep,
+        max_batch_get_items: int = BATCH_GET_MAX_KEYS,
+    ) -> None:
+        self._client = client
+        self._boto_errors = boto_errors
+        self._on_request = on_request
+        self._sleep = sleep
+        self._max_batch_get_items = max_batch_get_items
+
+    def get(
+        self,
+        physical_table: str,
+        serialized_keys: List[Dict[str, Any]],
+        request_extra: Optional[Dict[str, Any]] = None,
+    ) -> List[Dict[str, Any]]:
+        if not serialized_keys:
+            return []
+
+        items: List[Dict[str, Any]] = []
+        for batch in chunk(serialized_keys, self._max_batch_get_items):
+            items.extend(
+                self._get_chunk(physical_table, batch, request_extra or {})
+            )
+        return items
+
+    def _get_chunk(
+        self,
+        physical_table: str,
+        keys: List[Dict[str, Any]],
+        request_extra: Dict[str, Any],
+    ) -> List[Dict[str, Any]]:
+        pending = keys
+        attempt = 0
+        out: List[Dict[str, Any]] = []
+
+        while pending:
+            table_request = {"Keys": pending, **request_extra}
+            if self._on_request is not None:
+                self._on_request(len(pending))
+            try:
+                resp = self._client.batch_get_item(
+                    RequestItems={physical_table: table_request}
+                )
+            except self._boto_errors as exc:  # type: ignore[misc]
+                from .errors import OperationExecutionError
+
+                raise OperationExecutionError(
+                    f"BatchGetItem failed for table {physical_table!r}: {exc}",
+                    original=exc,
+                ) from exc
+
+            out.extend(resp.get("Responses", {}).get(physical_table, []))
+
+            unprocessed = (
+                resp.get("UnprocessedKeys", {})
+                .get(physical_table, {})
+                .get("Keys", [])
+            )
+            if not unprocessed:
+                break
+
+            if attempt >= BATCH_MAX_RETRY_ATTEMPTS:
+                from .errors import OperationExecutionError
+
+                raise OperationExecutionError(
+                    f"BatchGet exceeded the maximum of {BATCH_MAX_RETRY_ATTEMPTS} "
+                    f"retry attempts with {len(unprocessed)} key(s) still "
+                    f"unprocessed for table {physical_table!r} (likely sustained "
+                    f"throttling)."
+                )
+
+            pending = unprocessed
+            attempt += 1
+            self._sleep(compute_backoff_delay(attempt))
+
+        return out
+
+
+class BatchWriteExecutor:
+    """Executes a chunked, retrying ``BatchWriteItem`` against a boto3 client.
+
+    Port of the TypeScript batch-write semantics
+    (``src/operations/batch-retry.ts`` ``batchWriteChunkWithRetry`` +
+    ``src/operations/batch.ts`` ``executeBatchWrite``): the per-table write
+    requests (``{"PutRequest": {"Item": …}}`` / ``{"DeleteRequest": {"Key": …}}``,
+    AttributeValue shapes) are split into chunks of at most
+    :data:`BATCH_WRITE_MAX_ITEMS` (25); each chunk retries ``UnprocessedItems``
+    with the same exponential backoff as :class:`BatchGetExecutor` up to
+    :data:`BATCH_MAX_RETRY_ATTEMPTS` attempts, then raises.
+
+    ``BatchWriteItem`` carries **no conditions** (DynamoDB has no per-request
+    ``ConditionExpression`` for it) and is **not atomic** — both are properties of
+    the command-contract ``'batchWrite'`` mode (issue #64). The sleep is injected
+    so unit tests can observe the backoff schedule without real delays.
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        *,
+        boto_errors: tuple = (),
+        on_request: Optional[Callable[[int], None]] = None,
+        sleep: Callable[[float], None] = time.sleep,
+        max_batch_write_items: int = BATCH_WRITE_MAX_ITEMS,
+    ) -> None:
+        self._client = client
+        self._boto_errors = boto_errors
+        self._on_request = on_request
+        self._sleep = sleep
+        self._max_batch_write_items = max_batch_write_items
+
+    def write(self, physical_table: str, requests: List[Dict[str, Any]]) -> None:
+        """Apply every write request to ``physical_table``, chunked + retried."""
+        if not requests:
+            return
+        for batch in chunk(requests, self._max_batch_write_items):
+            self._write_chunk(physical_table, batch)
+
+    def _write_chunk(
+        self, physical_table: str, requests: List[Dict[str, Any]]
+    ) -> None:
+        pending = requests
+        attempt = 0
+
+        while pending:
+            if self._on_request is not None:
+                self._on_request(len(pending))
+            try:
+                resp = self._client.batch_write_item(
+                    RequestItems={physical_table: pending}
+                )
+            except self._boto_errors as exc:  # type: ignore[misc]
+                from .errors import OperationExecutionError
+
+                raise OperationExecutionError(
+                    f"BatchWriteItem failed for table {physical_table!r}: {exc}",
+                    original=exc,
+                ) from exc
+
+            unprocessed = resp.get("UnprocessedItems", {}).get(physical_table, [])
+            if not unprocessed:
+                break
+
+            if attempt >= BATCH_MAX_RETRY_ATTEMPTS:
+                from .errors import OperationExecutionError
+
+                raise OperationExecutionError(
+                    f"BatchWrite exceeded the maximum of {BATCH_MAX_RETRY_ATTEMPTS} "
+                    f"retry attempts with {len(unprocessed)} item(s) still "
+                    f"unprocessed for table {physical_table!r} (likely sustained "
+                    f"throttling)."
+                )
+
+            pending = unprocessed
+            attempt += 1
+            self._sleep(compute_backoff_delay(attempt))

graphddb_runtime/concurrency.py

@@ -0,0 +1,87 @@
+"""Bounded-concurrency staged execution (issue #70b).
+
+The static planner records an **execution plan** in the SSoT (issue #70a): a
+query's :class:`OperationSpec`\\ s are partitioned into ordered *stages*, where the
+operations **within** a stage are mutually independent (none reads a
+``{result.*}`` value another produces) and so may be issued concurrently, while
+the stages run in order. A contract method mirrors this for its External Query
+compositions. This module is the Python runtime's executor for that plan: it runs
+the independent work of one stage with a bounded number of in-flight workers, the
+faithful counterpart of the TypeScript runtime's ``mapWithConcurrency``
+(``src/relation/concurrency.ts``).
+
+## Why threads (and not asyncio)
+
+The runtime core is **synchronous** — it drives ``boto3``, a synchronous SDK
+(see ``async_runtime.py``: the async surface is a thin ``asyncio.to_thread``
+wrapper over this same sync core). A DynamoDB request is network I/O, during
+which ``boto3``/``botocore`` release the GIL, so a :class:`ThreadPoolExecutor`
+gives **real wall-clock overlap** for the independent requests of a stage while
+keeping a single executor implementation (no sync/async fork). The default bound
+is the same declared value the TS runtime uses (16), carried in the serialized
+plan as ``concurrency``.
+
+## Ordering guarantee
+
+:func:`map_with_concurrency` returns results in **input order**
+(``output[i]`` is ``worker(items[i])``) regardless of completion order, exactly
+like the TS helper. Stage consumers that mutate a shared result tree must still
+ensure each worker writes a **disjoint** slot (its own parent / property), which
+the relation-assembly and composition call sites do — completion order is then
+irrelevant to the merged output.
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable, List, Sequence, TypeVar
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+#: The default declared in-flight bound, mirroring the TypeScript
+#: ``RELATION_TRAVERSAL_CONCURRENCY`` (``src/relation/concurrency.ts``). A spec's
+#: ``executionPlan.concurrency`` overrides it; this is the fallback when a plan is
+#: absent or omits the field.
+RELATION_TRAVERSAL_CONCURRENCY = 16
+
+
+def map_with_concurrency(
+    items: Sequence[T],
+    limit: int,
+    worker: Callable[[T, int], R],
+) -> List[R]:
+    """Map ``items`` to results by invoking ``worker(item, index)`` with at most
+    ``limit`` workers in flight, preserving input order in the output.
+
+    Behaves like ``[worker(x, i) for i, x in enumerate(items)]`` but never runs
+    more than ``limit`` workers concurrently — the faithful counterpart of the
+    TypeScript ``mapWithConcurrency``. Independent boto3 round trips therefore
+    overlap (the SDK releases the GIL during I/O) under the declared bound.
+
+    - An empty input returns ``[]`` without spawning a pool.
+    - A single item (or ``limit <= 1``) runs **inline** on the calling thread, so
+      a non-staged / one-op-per-stage execution is byte-for-byte the pre-#70b
+      sequential path (no pool, no thread hand-off) — the backward-compatible
+      fallback.
+    - The first worker exception propagates (the pool is shut down); this mirrors
+      ``Promise.all`` rejecting on the first failure.
+    """
+    n = len(items)
+    if n == 0:
+        return []
+
+    effective = max(1, min(limit, n))
+    # Inline fast path: nothing to parallelize → run on the calling thread, no
+    # pool. Keeps a single-op-per-stage plan identical to sequential execution.
+    if effective == 1 or n == 1:
+        return [worker(item, i) for i, item in enumerate(items)]
+
+    results: List[R] = [None] * n  # type: ignore[list-item]
+    with ThreadPoolExecutor(max_workers=effective) as pool:
+        futures = {
+            pool.submit(worker, item, i): i for i, item in enumerate(items)
+        }
+        for future, i in futures.items():
+            results[i] = future.result()
+    return results

graphddb_runtime/cursor.py

@@ -0,0 +1,49 @@
+"""Pagination cursor encode/decode (issue #44).
+
+A cursor is the DynamoDB ``LastEvaluatedKey`` encoded as base64url-without-pad
+JSON, matching the TypeScript ``encodeCursor`` / ``decodeCursor``
+(``src/pagination/cursor.ts``): the JSON is the key object only — no wrapping
+``{table, index, ...}`` envelope — so the byte shape is identical for a given
+key.
+
+The runtime works with the **deserialized** (plain Python) key produced by
+``TypeDeserializer`` so the encoded JSON matches the un-marshalled shape the TS
+runtime (lib-dynamodb) encodes. ``encode_cursor`` accepts whatever JSON-safe
+mapping it is given; numbers from a deserialized key arrive as ``Decimal`` and
+are rendered as plain JSON numbers.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from decimal import Decimal
+from typing import Any, Mapping
+
+
+def _default(value: Any) -> Any:
+    if isinstance(value, Decimal):
+        # Render as int when integral, else float — mirrors JSON.stringify(Number).
+        return int(value) if value == value.to_integral_value() else float(value)
+    if isinstance(value, (bytes, bytearray)):
+        return base64.b64encode(bytes(value)).decode("ascii")
+    raise TypeError(f"Cannot encode {type(value).__name__} into a cursor")
+
+
+def encode_cursor(last_evaluated_key: Mapping[str, Any]) -> str:
+    """Encode a (deserialized) ``LastEvaluatedKey`` into a base64url cursor."""
+    payload = json.dumps(
+        last_evaluated_key,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        default=_default,
+    )
+    raw = base64.urlsafe_b64encode(payload.encode("utf-8")).decode("ascii")
+    return raw.rstrip("=")
+
+
+def decode_cursor(cursor: str) -> dict:
+    """Decode a base64url cursor back into a plain ``ExclusiveStartKey`` dict."""
+    padding = "=" * (-len(cursor) % 4)
+    payload = base64.urlsafe_b64decode((cursor + padding).encode("ascii"))
+    return json.loads(payload.decode("utf-8"))

graphddb_runtime/errors.py

@@ -0,0 +1,80 @@
+"""Error hierarchy for the GraphDDB Python runtime (issue #44).
+
+Mirrors the error taxonomy sketched in ``docs/python-bridge.md``.
+Every runtime-raised error derives from :class:`GraphDDBError` so callers can
+catch the whole family with a single ``except``.
+"""
+
+from __future__ import annotations
+
+
+class GraphDDBError(Exception):
+    """Base class for every error raised by the runtime."""
+
+
+class QueryNotFoundError(GraphDDBError):
+    """Raised when an ``execute_query`` is given an unknown ``query_id``."""
+
+
+class CommandNotFoundError(GraphDDBError):
+    """Raised when an ``execute_command`` is given an unknown ``command_id``."""
+
+
+class TransactionNotFoundError(GraphDDBError):
+    """Raised when an ``execute_transaction`` is given an unknown id (issue #46)."""
+
+
+class ContractNotFoundError(GraphDDBError):
+    """Raised when an ``execute_query_method`` names an unknown contract / method.
+
+    Covers an unknown contract name, an unknown method on a known contract, or a
+    method whose ``kind`` does not match the call (e.g. a command method invoked
+    through the query path). Issue #62 (single-service contract Runtime).
+    """
+
+
+class ContractArityError(GraphDDBError):
+    """Raised when a contract method is called with the wrong input arity.
+
+    Specifically, an **array** of keys fed into a ``range`` method (whose
+    ``inputArity`` is ``'single'``): a range resolution is one partition ``Query``
+    per key, so an array would be an N+1 fan-out forbidden by the contract's N+1
+    rule. The caller must loop in application code if N independent range reads
+    are genuinely needed. Issue #62.
+    """
+
+
+class ParameterValidationError(GraphDDBError):
+    """Raised before any DynamoDB call when params fail validation.
+
+    Covers a missing required param, an unknown param, a wrong scalar type, or a
+    ``literal`` param whose value is not in the allowed set.
+    """
+
+
+class LimitExceededError(GraphDDBError):
+    """Raised before any DynamoDB call when a runtime limit would be exceeded."""
+
+
+class OperationExecutionError(GraphDDBError):
+    """Wraps a boto3 ``ClientError`` (or any boto3 failure) from a DynamoDB call.
+
+    The original exception is preserved as ``__cause__`` and on ``original``.
+    """
+
+    def __init__(self, message: str, original: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.original = original
+
+
+class HydrationError(GraphDDBError):
+    """Raised when a raw DynamoDB item cannot be hydrated into a result."""
+
+
+class MultiOperationNotSupportedError(GraphDDBError):
+    """Raised when a query/command spec needs more than the single-op core.
+
+    Relation chains (operations whose length is > 1, or ops carrying a
+    ``sourceField``) are out of scope for issue #44 and are handled by the
+    relation runtime in issue #45.
+    """