graphddb-runtime 0.1.0__py3-none-any.whl

graphddb_runtime/templates.py

@@ -0,0 +1,131 @@
+"""Parameter validation and ``{param}`` template resolution (issue #44).
+
+Templates follow the #42 ``OperationSpec`` form: a value such as
+``EMAIL#{email}`` or ``USER#{userId}`` contains zero or more ``{name}``
+placeholders bound from caller params. ``{result.field}`` placeholders are
+relation-chain bindings and never appear in the single-operation core; a
+template carrying one is rejected as out of scope by the executor before this
+module is reached.
+
+A value with no ``{...}`` is a literal (e.g. the discriminator ``PROFILE`` or a
+serialized ``Date`` like ``1970-01-01T00:00:00.000Z``).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping
+
+from .errors import ParameterValidationError
+
+# A placeholder is `{` + name (no dot) + `}`. `{result.*}` is matched but flagged
+# separately by the executor so it can raise the multi-op error.
+_PLACEHOLDER = re.compile(r"\{([^{}]+)\}")
+
+
+def validate_params(
+    params: Mapping[str, Any],
+    param_specs: Mapping[str, Mapping[str, Any]],
+    *,
+    operation_id: str,
+) -> None:
+    """Validate caller params against the spec's ``params`` declaration.
+
+    Raises :class:`ParameterValidationError` (before any DynamoDB call) on a
+    missing required param, an unknown param, a wrong scalar type, or a
+    ``literal`` value outside the allowed set.
+    """
+    for name, spec in param_specs.items():
+        required = bool(spec.get("required", False))
+        present = name in params and params[name] is not None
+        if required and not present:
+            raise ParameterValidationError(
+                f"{operation_id}: missing required parameter '{name}'"
+            )
+        if not present:
+            continue
+        _check_value(operation_id, name, spec, params[name])
+
+    for name in params:
+        if name not in param_specs:
+            raise ParameterValidationError(
+                f"{operation_id}: unknown parameter '{name}'"
+            )
+
+
+def _check_value(
+    operation_id: str, name: str, spec: Mapping[str, Any], value: Any
+) -> None:
+    kind = spec.get("type")
+    if kind == "number":
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ParameterValidationError(
+                f"{operation_id}: parameter '{name}' must be a number"
+            )
+    elif kind == "boolean":
+        if not isinstance(value, bool):
+            raise ParameterValidationError(
+                f"{operation_id}: parameter '{name}' must be a boolean"
+            )
+    elif kind == "literal":
+        literals = spec.get("literals") or []
+        if value not in literals:
+            allowed = ", ".join(repr(lit) for lit in literals)
+            raise ParameterValidationError(
+                f"{operation_id}: parameter '{name}' must be one of [{allowed}], got {value!r}"
+            )
+    elif kind == "array":
+        # An array param (transaction forEach source): a list whose elements each
+        # validate against the element field specs.
+        if not isinstance(value, list):
+            raise ParameterValidationError(
+                f"{operation_id}: parameter '{name}' must be an array"
+            )
+        element_specs = spec.get("element") or {}
+        for index, element in enumerate(value):
+            if not isinstance(element, dict):
+                raise ParameterValidationError(
+                    f"{operation_id}: parameter '{name}'[{index}] must be an object"
+                )
+            for field, field_spec in element_specs.items():
+                present = field in element and element[field] is not None
+                if field_spec.get("required", False) and not present:
+                    raise ParameterValidationError(
+                        f"{operation_id}: parameter '{name}'[{index}] missing "
+                        f"required field '{field}'"
+                    )
+                if present:
+                    _check_value(
+                        operation_id, f"{name}[{index}].{field}", field_spec,
+                        element[field],
+                    )
+    else:  # 'string' and any other scalar default to string.
+        if not isinstance(value, str):
+            raise ParameterValidationError(
+                f"{operation_id}: parameter '{name}' must be a string"
+            )
+
+
+def has_result_placeholder(template: str) -> bool:
+    """True if the template references a prior result (``{result.*}``)."""
+    return any(m.group(1).startswith("result.") for m in _PLACEHOLDER.finditer(template))
+
+
+def resolve_template(template: str, params: Mapping[str, Any]) -> str:
+    """Substitute ``{param}`` placeholders in ``template`` with param values.
+
+    The whole value is returned as a string (key/sort-key values are strings in
+    the single-table layout). Missing params should have been caught by
+    :func:`validate_params`; a stray placeholder here raises
+    :class:`ParameterValidationError`.
+    """
+
+    def repl(match: "re.Match[str]") -> str:
+        name = match.group(1)
+        if name not in params or params[name] is None:
+            raise ParameterValidationError(
+                f"template '{template}' references unbound parameter '{name}'"
+            )
+        return str(params[name])
+
+    return _PLACEHOLDER.sub(repl, template)

graphddb_runtime/transactions.py

@@ -0,0 +1,440 @@
+"""Declarative transaction expansion + execution (issue #46, Phase 4).
+
+Interprets a serializable ``TransactionSpec`` (from ``operations.json``): expands
+each templated item with the caller params (and, for ``forEach`` items, each
+element of the named array param), derives PK/SK/GSI key attributes from the
+manifest exactly as the single-write path does, builds a boto3
+``transact_write_items`` request (≤25), and executes it. A failed transaction
+(``TransactionCanceledException``) is wrapped in ``OperationExecutionError``,
+matching the single-write error policy.
+
+Template forms mirror the planner and the TS executor: ``{param}`` resolves from
+the caller params; ``{item.<field>}`` resolves from the current ``forEach``
+element. A leaf with no placeholder is a literal.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Mapping, Optional
+
+_PLACEHOLDER_RE = re.compile(r"\{[^{}]+\}")
+_WHOLE_PLACEHOLDER_RE = re.compile(r"^\{[^{}]+\}$")
+
+MAX_TRANSACT_ITEMS = 25
+
+
+def _resolve_template(
+    template: str,
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+) -> str:
+    """Resolve ``{param}`` / ``{item.field}`` placeholders to a string."""
+
+    def repl(match: "re.Match[str]") -> str:
+        name = match.group(0)[1:-1]
+        if name.startswith("item."):
+            field = name[len("item.") :]
+            if element is None or field not in element:
+                raise KeyError(
+                    f"element field '{field}' not bound for template '{template}'"
+                )
+            return str(element[field])
+        if name not in params or params[name] is None:
+            raise KeyError(f"template '{template}' references unbound param '{name}'")
+        return str(params[name])
+
+    return _PLACEHOLDER_RE.sub(repl, template)
+
+
+def _resolve_value(
+    template: str,
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+) -> Any:
+    """Resolve a value template, keeping the typed value for a whole placeholder."""
+    if _WHOLE_PLACEHOLDER_RE.match(template):
+        name = template[1:-1]
+        if name.startswith("item."):
+            field = name[len("item.") :]
+            if element is not None and field in element:
+                return element[field]
+        elif name in params and params[name] is not None:
+            return params[name]
+    return _resolve_template(template, params, element)
+
+
+def _resolve_record(
+    record: Optional[Mapping[str, str]],
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+) -> Dict[str, Any]:
+    return {
+        field: _resolve_value(tmpl, params, element)
+        for field, tmpl in (record or {}).items()
+    }
+
+
+def _fill_key(template: str, item: Mapping[str, Any]) -> str:
+    def repl(match: "re.Match[str]") -> str:
+        name = match.group(0)[1:-1]
+        return str(item.get(name, ""))
+
+    return _PLACEHOLDER_RE.sub(repl, template)
+
+
+def _key_fillable(template: str, item: Mapping[str, Any]) -> bool:
+    return all(m.group(0)[1:-1] in item for m in _PLACEHOLDER_RE.finditer(template))
+
+
+def _when_holds(
+    when: Mapping[str, Any],
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+) -> bool:
+    left = _resolve_template(when["left"], params, element)
+    right = _resolve_template(when["right"], params, element)
+    return left == right if when["op"] == "eq" else left != right
+
+
+def _attr_str(value: Any) -> str:
+    """The string form of a serialized DynamoDB attribute value (PK/SK are strings)."""
+    if isinstance(value, Mapping):
+        # Serialized boto3 attribute value, e.g. {"S": "UNIQUE#..."}; take the inner.
+        return str(next(iter(value.values()))) if value else ""
+    return str(value)
+
+
+def _item_kind(item: Mapping[str, Any]) -> str:
+    for kind in ("Put", "Update", "Delete", "ConditionCheck"):
+        if kind in item:
+            return kind
+    raise ValueError(f"transact item has no recognized op: {sorted(item)}")
+
+
+def _item_key_signature(item: Mapping[str, Any]) -> str:
+    """The ``(table, PK, SK)`` signature of a built transact item, for the collapse.
+
+    A ``Put`` carries its key in ``Item.PK`` / ``Item.SK``; the others in
+    ``Key.PK`` / ``Key.SK``. Values are serialized boto3 attribute values.
+    """
+    kind = _item_kind(item)
+    body = item[kind]
+    rec = body.get("Item") if kind == "Put" else body.get("Key")
+    rec = rec or {}
+    table = body.get("TableName", "")
+    return f"{table}#{_attr_str(rec.get('PK'))}#{_attr_str(rec.get('SK'))}"
+
+
+def _merge_add_updates(updates: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Merge several same-key atomic-``ADD`` ``Update`` items into ONE, summing the
+    deltas per target attribute.
+
+    An edge move with ``old == new`` derives ``counter -= 1`` AND ``counter += 1`` on
+    the SAME row (#92): two operations on one item are rejected, so they fold into a
+    single net-zero ADD (a legal single write). Each item is an ADD built like the TS
+    ``renderDerivedUpdate`` (``ADD #aN :aN``); a numeric value (serialized ``{"N": …}``)
+    is summed, mirroring the TS ``mergeAddUpdates`` so the same SSoT yields one identical
+    ADD.
+    """
+    first = updates[0]["Update"]
+    deltas: Dict[str, int] = {}
+    for it in updates:
+        upd = it["Update"]
+        names = upd.get("ExpressionAttributeNames", {})
+        values = upd.get("ExpressionAttributeValues", {})
+        for name_ph, attr in names.items():
+            value_ph = f":{name_ph[1:]}"
+            serialized = values.get(value_ph, {})
+            # A serialized DynamoDB number attribute, e.g. {"N": "1"}.
+            raw = serialized.get("N") if isinstance(serialized, Mapping) else serialized
+            deltas[attr] = deltas.get(attr, 0) + int(raw)
+    names_out: Dict[str, str] = {}
+    values_out: Dict[str, Any] = {}
+    clauses: List[str] = []
+    for i, (attr, delta) in enumerate(deltas.items()):
+        names_out[f"#a{i}"] = attr
+        values_out[f":a{i}"] = {"N": str(delta)}
+        clauses.append(f"#a{i} :a{i}")
+    return {
+        "Update": {
+            "TableName": first["TableName"],
+            "Key": first["Key"],
+            "UpdateExpression": "ADD " + ", ".join(clauses),
+            "ExpressionAttributeNames": names_out,
+            "ExpressionAttributeValues": values_out,
+        }
+    }
+
+
+def _collapse_same_key_items(items: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Collapse items that target the SAME physical row (``(table, PK, SK)``).
+
+    The op-aware rule the TS in-process runtime (``collapseSameKeyItems``) applies
+    identically (issues #85, #86, #92). A ``TransactWriteItems`` may not touch one key
+    twice, so a same-key collision is always one of these derivation shapes:
+
+    - a **``Delete(old) + Put(new)`` swap pair** that resolved to the same key — a
+      uniqueness guard whose unique field did NOT change (#86), or an edge move with
+      ``old == new`` (#92): a **net no-op**, emit NEITHER (keeping the ``Put`` would
+      fail its ``attribute_not_exists`` against the already-claimed row; keeping the
+      ``Delete`` would drop a still-needed guard / edge — both wrong);
+    - **multiple ``Put``s (or multiple ``Delete``s) of the same modeled row** (one write
+      op, no swap — the self-row edge de-dup, #85): a derived edge Put targets the same row
+      a base Put writes (create), or a derived edge Delete targets the same row a base
+      Delete removes (remove): keep the FIRST, drop the rest;
+    - **multiple ``Update`` (ADD) counters on the same row** — an edge move with
+      ``old == new`` derives two ADDs on one counter (#92): MERGE them into one ADD with
+      the deltas summed per attribute (net ``0`` for the symmetric ±1).
+
+    A **``Put`` + ``Update`` collision** — a base entity write and a derived counter ADD
+    on the SAME row (issue #93) — is NOT a safe collapse shape: it is REJECTED loudly. The
+    build-time guard catches the statically determinable self-target, but an ALIASED
+    self-target (a counter keyed off a differently-named input the caller passes equal to
+    the write's key) only coincides at runtime and evades the static guard and the
+    distinct-template backstop. Folding it into the self-row Put de-dup would silently drop
+    the ADD — the exact silent-drop #93 forbids — so this and any other unhandled same-key
+    op combination raise rather than collapse.
+
+    A genuine swap (``old != new``) resolves to two distinct keys, so both survive.
+    First-seen order is preserved (a merged ADD takes the position of the FIRST update
+    in its bucket), so the output is identical to the TS runtimes' for the same SSoT.
+    """
+    groups: Dict[str, List[Dict[str, Any]]] = {}
+    for item in items:
+        sig = _item_key_signature(item)
+        groups.setdefault(sig, []).append(item)
+    out: List[Dict[str, Any]] = []
+    for item in items:
+        sig = _item_key_signature(item)
+        bucket = groups[sig]
+        if len(bucket) == 1:
+            out.append(item)
+            continue
+        kinds = {_item_kind(b) for b in bucket}
+        if "Delete" in kinds and "Put" in kinds:
+            # Swap pair resolved to one key → net no-op: drop EVERY member at this key.
+            continue
+        if "Put" in kinds and "Update" in kinds:
+            # Base entity Put + derived counter Update(ADD) on the SAME row (issue #93,
+            # the aliased self-target that evades the build-time guard). A Put+Update on
+            # one item is unsupported (DynamoDB rejects touching one key twice) and
+            # collapsing it would silently drop the increment — FAIL LOUDLY instead.
+            raise ValueError(
+                "a derived counter (`increment`) resolves to the SAME item as the "
+                "entity write at runtime (the call-time key values made an aliased "
+                "target coincide with the written row). A Put+Update on one transaction "
+                "item is unsupported — DynamoDB rejects touching one key twice, and "
+                "collapsing it would silently drop the increment. A `w.increment(...)` "
+                "must target a DIFFERENT row (e.g. a parent aggregate's counter); to "
+                "maintain a counter ON the written entity, write the field as part of "
+                "the entity itself, not via a derived counter onto its own row."
+            )
+        if item is not bucket[0]:
+            # Non-first members are folded into / dropped by the first member's handling.
+            continue
+        if kinds == {"Update"}:
+            # Same-key counter ADDs (an edge move with old==new) → one merged ADD.
+            out.append(_merge_add_updates(bucket))
+        elif kinds in ({"Put"}, {"Delete"}):
+            # Self-row edge de-dup (#85): a derived edge Put targets the same row a base
+            # Put writes (create), or a derived edge Delete targets the same row a base
+            # Delete removes (remove). The op is idempotent on one key — keep the FIRST.
+            out.append(item)
+        else:
+            # No other same-key op combination is a known-safe derivation shape. Reject
+            # loudly rather than silently collapse / drop an item.
+            raise ValueError(
+                f"{len(bucket)} transaction items resolve to the same physical row with "
+                f"an unsupported op combination ({'+'.join(sorted(kinds))}). A "
+                "TransactWriteItems may not touch one key twice; this collision is not a "
+                "known collapse shape (self-row Put/Delete de-dup, swap no-op, or "
+                "symmetric counter ADDs), so it is rejected rather than silently collapsed."
+            )
+    return out
+
+
+class TransactionExpander:
+    """Expands a transaction spec into serialized boto3 TransactItems.
+
+    Bound to a runtime so it can reuse the runtime's serializer, manifest
+    entities, and physical-table mapping.
+    """
+
+    def __init__(self, runtime: Any) -> None:
+        self._rt = runtime
+        self._serializer = runtime._serializer
+        self._entities = runtime._entities
+
+    def _entity(self, name: str) -> Mapping[str, Any]:
+        entity = self._entities.get(name)
+        if entity is None:
+            raise KeyError(f"unknown entity '{name}' in manifest")
+        return entity
+
+    def _add_key_attributes(self, entity_name: str, plain: Dict[str, Any]) -> None:
+        entity = self._entity(entity_name)
+        key = entity.get("key")
+        if key:
+            # pkTemplate is self-contained (segment key model #51); no prefix.
+            plain["PK"] = _fill_key(key.get("pkTemplate") or "", plain)
+            sk_tmpl = key.get("skTemplate")
+            if sk_tmpl is not None:
+                plain["SK"] = _fill_key(sk_tmpl, plain)
+        for gsi in entity.get("gsis", []):
+            index = gsi["indexName"]
+            pk_tmpl = gsi.get("pkTemplate")
+            sk_tmpl = gsi.get("skTemplate")
+            if pk_tmpl is not None and _key_fillable(pk_tmpl, plain):
+                plain[f"{index}PK"] = _fill_key(pk_tmpl, plain)
+            if sk_tmpl is not None and _key_fillable(sk_tmpl, plain):
+                plain[f"{index}SK"] = _fill_key(sk_tmpl, plain)
+
+    def _apply_condition(
+        self,
+        condition: Optional[Mapping[str, Any]],
+        target: Dict[str, Any],
+        params: Mapping[str, Any],
+        element: Optional[Mapping[str, Any]],
+    ) -> None:
+        if not condition:
+            return
+        names = target.setdefault("ExpressionAttributeNames", {})
+        kind = condition["kind"]
+        if kind == "notExists":
+            names["#pk"] = "PK"
+            target["ConditionExpression"] = "attribute_not_exists(#pk)"
+            return
+        if kind in ("attributeExists", "attributeNotExists"):
+            # attribute_(not_)exists on any field (incl. PK/SK), issue #81. Routed
+            # through a "#ce" placeholder so reserved words / key attributes are
+            # always legal.
+            fn = (
+                "attribute_exists"
+                if kind == "attributeExists"
+                else "attribute_not_exists"
+            )
+            names["#ce"] = condition["field"]
+            target["ConditionExpression"] = f"{fn}(#ce)"
+            return
+        values = target.setdefault("ExpressionAttributeValues", {})
+        clauses = []
+        for i, (field, tmpl) in enumerate(condition["fields"].items()):
+            n = f"#e{i}"
+            v = f":e{i}"
+            names[n] = field
+            values[v] = self._serializer.serialize(
+                _resolve_value(tmpl, params, element)
+            )
+            clauses.append(f"{n} = {v}")
+        target["ConditionExpression"] = " AND ".join(clauses)
+
+    def _build_item(
+        self,
+        spec: Mapping[str, Any],
+        params: Mapping[str, Any],
+        element: Optional[Mapping[str, Any]],
+    ) -> Dict[str, Any]:
+        entity_name = spec["entity"]
+        table = self._rt._physical_table(spec["tableName"])
+        item_type = spec["type"]
+
+        if item_type == "Put":
+            plain = _resolve_record(spec.get("item"), params, element)
+            # A raw marker-row write (issue #86 uniqueness guard) carries its PK/SK
+            # LITERALLY in the item — there is no manifest entity, so do NOT derive
+            # key attributes from metadata; write the resolved record verbatim. A
+            # modeled Put still derives PK/SK/GSI from the entity exactly as before.
+            if not spec.get("literalKey"):
+                self._add_key_attributes(entity_name, plain)
+            serialized = {
+                k: self._serializer.serialize(v) for k, v in plain.items()
+            }
+            put: Dict[str, Any] = {"TableName": table, "Item": serialized}
+            self._apply_condition(spec.get("condition"), put, params, element)
+            return {"Put": put}
+
+        key_plain = _resolve_record(spec.get("keyCondition"), params, element)
+        key = {k: self._serializer.serialize(v) for k, v in key_plain.items()}
+
+        if item_type == "Delete":
+            delete: Dict[str, Any] = {"TableName": table, "Key": key}
+            self._apply_condition(spec.get("condition"), delete, params, element)
+            return {"Delete": delete}
+
+        if item_type == "ConditionCheck":
+            # A read-only assertion (issue #81): no Item / changes, just a keyed row
+            # plus a mandatory ConditionExpression whose failure cancels the whole
+            # transaction.
+            condition = spec.get("condition")
+            if not condition:
+                raise ValueError(
+                    f"ConditionCheck on '{entity_name}' has no condition; a "
+                    f"ConditionCheck must carry the assertion it makes."
+                )
+            check: Dict[str, Any] = {"TableName": table, "Key": key}
+            self._apply_condition(condition, check, params, element)
+            return {"ConditionCheck": check}
+
+        # Update. Two distinct DynamoDB actions, both supported (issue #85):
+        #   - `changes` → `SET #f = :v` (overwrite a named field);
+        #   - `add`     → `ADD #f :delta` (atomic numeric increment, concurrency-safe;
+        #     a derived counter such as `User.postCount += 1` MUST be an ADD so a
+        #     concurrent increment is never clobbered — exactly the TS runtime's
+        #     `buildAddUpdateInput`).
+        changes = _resolve_record(spec.get("changes"), params, element)
+        adds = _resolve_record(spec.get("add"), params, element)
+        names: Dict[str, str] = {}
+        values: Dict[str, Any] = {}
+        sets: List[str] = []
+        add_clauses: List[str] = []
+        for i, (field, value) in enumerate(changes.items()):
+            n = f"#c{i}"
+            v = f":c{i}"
+            names[n] = field
+            values[v] = self._serializer.serialize(value)
+            sets.append(f"{n} = {v}")
+        for i, (field, value) in enumerate(adds.items()):
+            n = f"#a{i}"
+            v = f":a{i}"
+            names[n] = field
+            # An ADD delta is numeric; serialize it as a number even though the
+            # template rendered it to a string (the literal `"1"` / `"-1"`).
+            values[v] = self._serializer.serialize(int(value) if isinstance(value, str) else value)
+            add_clauses.append(f"{n} {v}")
+        update: Dict[str, Any] = {"TableName": table, "Key": key}
+        expr_parts: List[str] = []
+        if sets:
+            expr_parts.append("SET " + ", ".join(sets))
+        if add_clauses:
+            expr_parts.append("ADD " + ", ".join(add_clauses))
+        if expr_parts:
+            update["UpdateExpression"] = " ".join(expr_parts)
+            update["ExpressionAttributeNames"] = names
+            update["ExpressionAttributeValues"] = values
+        self._apply_condition(spec.get("condition"), update, params, element)
+        return {"Update": update}
+
+    def expand(
+        self, spec: Mapping[str, Any], params: Mapping[str, Any]
+    ) -> List[Dict[str, Any]]:
+        expanded: List[Dict[str, Any]] = []
+        for item in spec.get("items", []):
+            for_each = item.get("forEach")
+            when = item.get("when")
+            if for_each:
+                source = params.get(for_each["source"])
+                if not isinstance(source, list):
+                    raise TypeError(
+                        f"forEach source '{for_each['source']}' must be an array "
+                        f"param; got {type(source).__name__}"
+                    )
+                for element in source:
+                    if when and not _when_holds(when, params, element):
+                        continue
+                    expanded.append(self._build_item(item, params, element))
+            else:
+                if when and not _when_holds(when, params, None):
+                    continue
+                expanded.append(self._build_item(item, params, None))
+        return _collapse_same_key_items(expanded)