zero-server 0.0.1__py3-none-any.whl

zero_server/protocol/push.py

@@ -0,0 +1,25 @@
+"""What zero-cache POSTs to a mutate endpoint.
+
+Ported from rocicorp/mono `packages/zero-protocol/src/push.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+"""
+
+from pydantic import Field, StrictStr
+
+from zero_server.protocol.mutation import Mutation
+from zero_server.protocol.wire import Number, WireModel
+
+
+class PushBody(WireModel):
+    """Parsed in passthrough mode upstream, so keys it does not declare are ignored, not refused."""
+
+    client_group_id: StrictStr = Field(alias="clientGroupID")
+    mutations: list[Mutation]
+    push_version: Number = Field(alias="pushVersion")
+    # Only CRUD mutations are tied to a schema version.
+    schema_version: Number | None = Field(default=None, alias="schemaVersion")
+    timestamp: Number
+    request_id: StrictStr = Field(alias="requestID")
+    # Deprecated upstream: auth is per client group now, through connect and updateAuth.
+    auth: StrictStr | None = None
+    traceparent: StrictStr | None = None

zero_server/protocol/query_server.py

@@ -0,0 +1,29 @@
+"""The query endpoint's response.
+
+Ported from rocicorp/mono `packages/zero-protocol/src/query-server.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+"""
+
+from typing import Literal
+
+from pydantic import Field, StrictStr
+
+from zero_server.protocol.custom_queries import TransformResponseBody
+from zero_server.protocol.error import TransformFailedBody
+from zero_server.protocol.wire import WireModel
+
+
+class QuerySuccess(WireModel):
+    """`user_id` is reported to zero-cache only when the caller set it, `None` included.
+
+    Reporting it is what makes zero-cache trust the connection's user as server-validated.
+    """
+
+    nullable = frozenset({"user_id"})
+
+    kind: Literal["QueryResponse"] = "QueryResponse"
+    user_id: StrictStr | None = Field(default=None, alias="userID")
+    queries: TransformResponseBody
+
+
+type QueryResponse = QuerySuccess | TransformFailedBody

zero_server/protocol/wire.py

@@ -0,0 +1,88 @@
+"""The base every wire model shares.
+
+Upstream's optional fields are absent when unset, never `null`. zero-cache hashes the ASTs it receives,
+so `"limit": null` and no `limit` are two different queries to it. A model therefore drops a `None`
+field when it serializes, except a field listed in `nullable`, where `None` is a real JSON `null` and
+survives whenever the caller set it.
+
+Parsing is the mirror image: an optional field upstream may be absent but not `null`, so a `null` is
+refused unless the field is `nullable`.
+"""
+
+from typing import Any, ClassVar, Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    SerializerFunctionWrapHandler,
+    StrictFloat,
+    StrictInt,
+    TypeAdapter,
+    ValidationInfo,
+    model_serializer,
+    model_validator,
+)
+
+from zero_server.shared.json import JSONValue
+
+WIRE: Any = {"source": "wire"}
+"""Validation context marking a value as arriving off the wire rather than built in Python."""
+
+
+def parse_wire[T](adapter: TypeAdapter[T], value: object) -> T:
+    return adapter.validate_python(value, context=WIRE)
+
+
+class WireModel(BaseModel):
+    model_config = ConfigDict(
+        frozen=True,
+        populate_by_name=True,
+        serialize_by_alias=True,
+        extra="ignore",
+    )
+
+    nullable: ClassVar[frozenset[str]] = frozenset()
+
+    @model_validator(mode="before")
+    @classmethod
+    def _refuse_null_for_optional(cls, data: Any, info: ValidationInfo) -> Any:
+        if info.context == WIRE and isinstance(data, dict):
+            for name, field in cls.model_fields.items():
+                if name in cls.nullable or field.is_required():
+                    continue
+                for key in {name, field.alias or name}:
+                    if key in data and data[key] is None:
+                        raise ValueError(f"{key} may be absent but not null")
+        return data
+
+    @model_serializer(mode="wrap")
+    def _omit_unset(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
+        dumped: dict[str, Any] = handler(self)
+        out: dict[str, Any] = {}
+        for name, info in type(self).model_fields.items():
+            key = info.serialization_alias or info.alias or name
+            if key not in dumped:
+                continue
+            value = dumped[key]
+            if value is None and not (name in self.nullable and name in self.model_fields_set):
+                continue
+            out[key] = value
+        return out
+
+    def to_json(self) -> dict[str, JSONValue]:
+        """The JSON object upstream would send for this model."""
+        return self.model_dump(mode="json")
+
+    @classmethod
+    def from_json(cls, value: object) -> Self:
+        return cls.model_validate(value, context=WIRE)
+
+
+type Number = StrictInt | StrictFloat
+"""A JSON number. `bool` is not one, though Python says otherwise."""
+
+
+class StrictWireModel(WireModel):
+    """Refuses keys it does not declare, as upstream's default (strict) parse mode does."""
+
+    model_config = ConfigDict(extra="forbid")

zero_server/query/__init__.py

@@ -0,0 +1 @@
+"""ZQL's query builder and query registry, from rocicorp/mono `packages/zql/src/query`."""

zero_server/query/builder.py

@@ -0,0 +1,338 @@
+"""The ZQL query builder: a `Query` is an immutable AST under construction, in client names.
+
+Ported from rocicorp/mono `packages/zql/src/query/query-impl.ts` and `create-builder.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+
+The errors match upstream's message for message, because a query endpoint reports them to the client.
+"""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field, replace
+from typing import Any, Generic
+
+from typing_extensions import TypeVar
+
+from zero_server.protocol.ast import (
+    AST,
+    SUBQ_PREFIX,
+    Bound,
+    Condition,
+    CorrelatedSubquery,
+    CorrelatedSubqueryCondition,
+    Correlation,
+    Direction,
+    System,
+)
+from zero_server.query.expression import MISSING, ExpressionBuilder, and_, cmp, simplify_condition
+from zero_server.schema import Connection, Schema
+from zero_server.shared.asserts import check
+
+
+@dataclass(frozen=True)
+class Format:
+    """The shape of a query's result: a row or a list, and the same for each relationship."""
+
+    singular: bool = False
+    relationships: dict[str, "Format"] = field(default_factory=dict)
+
+
+R = TypeVar("R", default=dict[str, Any])
+"""A row of the query's table, as `tx.run` returns it. Generated schema types narrow it."""
+C = TypeVar("C", bound=str, default=str)
+"""The table's column names. Generated schema types narrow it to a `Literal`."""
+
+type AnyQuery = "Query[Any, Any]"
+type SubqueryFn = Callable[[Any], Any]
+
+
+class UnknownColumnError(Exception):
+    """A strict builder refused a column its table does not have."""
+
+
+class Query(Generic[R, C]):
+    """An immutable query on one table. Every method returns a new query."""
+
+    def __init__(
+        self,
+        schema: Schema,
+        table: str,
+        ast: AST,
+        system: System = "client",
+        current_junction: str | None = None,
+        format: Format | None = None,
+        *,
+        strict: bool = False,
+    ) -> None:
+        self._schema = schema
+        self._table = table
+        self._ast = ast
+        self._system: System = system
+        self._junction = current_junction
+        self._format = format or Format()
+        self._strict = strict
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._ast.to_json()!r})"
+
+    def _check_column(self, column: str) -> None:
+        if self._strict and column not in self._schema.tables[self._table].columns:
+            raise UnknownColumnError(f'unknown column "{column}" of "{self._table}" table')
+
+    @property
+    def format(self) -> Format:
+        return self._format
+
+    @property
+    def ast(self) -> AST:
+        """The AST in client names. The query endpoint maps it to server names."""
+        return self._ast
+
+    @property
+    def table(self) -> str:
+        return self._table
+
+    def _new(self, table: str, ast: AST, junction: str | None, format: Format | None = None) -> AnyQuery:
+        return Query(self._schema, table, ast, self._system, junction, format, strict=self._strict)
+
+    def _with[Q: Query[Any, Any]](self: Q, format: Format | None = None, **update: Any) -> Q:
+        return type(self)(
+            self._schema,
+            self._table,
+            self._ast.model_copy(update=update),
+            self._system,
+            self._junction,
+            format or self._format,
+            strict=self._strict,
+        )
+
+    def _with_relationship[Q: Query[Any, Any]](self: Q, name: str, sub: AnyQuery, entry: CorrelatedSubquery) -> Q:
+        format = replace(self._format, relationships={**self._format.relationships, name: sub.format})
+        return self._with(format=format, related=(*(self._ast.related or ()), entry))
+
+    def one(self) -> "OneQuery[R, C]":
+        """At most one row: `tx.run` returns it, or `None`."""
+        query = self._with(format=replace(self._format, singular=True), limit=1)
+        return OneQuery(
+            query._schema, query._table, query._ast, query._system, query._junction, query._format, strict=self._strict
+        )
+
+    def where[Q: Query[Any, Any]](
+        self: Q, field_or_factory: C | Callable[[ExpressionBuilder], Condition], *args: Any
+    ) -> Q:
+        """`where(field, value)`, `where(field, op, value)`, or `where(lambda eb: ...)`."""
+        cond: Condition
+        if isinstance(field_or_factory, str):
+            self._check_column(field_or_factory)
+            check(len(args) >= 1, "Invalid condition. Too few arguments.")
+            cond = cmp(field_or_factory, args[0]) if len(args) == 1 else cmp(field_or_factory, args[0], args[1])
+        else:
+            cond = field_or_factory(self.expression_builder())
+        if self._ast.where is not None:
+            cond = and_(self._ast.where, cond)
+        return self._with(where=simplify_condition(cond))
+
+    def where_exists[Q: Query[Any, Any]](
+        self: Q,
+        relationship: str,
+        cb: SubqueryFn | None = None,
+        *,
+        flip: bool | None = None,
+        scalar: bool | None = None,
+    ) -> Q:
+        return self.where(lambda eb: eb.exists(relationship, cb, flip=flip, scalar=scalar))
+
+    def _relationship(self, relationship: str) -> tuple[Connection, ...]:
+        by_table = self._schema.relationships.get(self._table)
+        if by_table is None:
+            raise TypeError(f"Cannot read properties of undefined (reading '{relationship}')")
+        related = by_table.get(relationship)
+        check(related, "Invalid relationship")
+        assert related is not None
+        return related
+
+    def related[Q: Query[Any, Any]](self: Q, relationship: str, cb: SubqueryFn | None = None) -> Q:
+        """Nest the rows of `relationship` under each row, shaped by `cb` if given."""
+        if relationship.startswith(SUBQ_PREFIX):
+            raise Exception(f'Relationship names may not start with "{SUBQ_PREFIX}". That is a reserved prefix.')
+        cb = cb or (lambda q: q)
+        related = self._relationship(relationship)
+        if len(related) == 1:
+            (hop,) = related
+            q = self._new(
+                hop.dest_schema,
+                AST(table=hop.dest_schema, alias=relationship),
+                None,
+                Format(singular=hop.cardinality == "one"),
+            )
+            sub = _as_query(cb(q))
+            check(len(hop.source_field) >= 1, "The source of a relationship must specify at last 1 field")
+            check(len(hop.dest_field) >= 1, "The destination of a relationship must specify at last 1 field")
+            check(
+                len(hop.source_field) == len(hop.dest_field),
+                "The source and destination of a relationship must have the same number of fields",
+            )
+            entry = CorrelatedSubquery(
+                system=self._system,
+                correlation=Correlation(parent_field=hop.source_field, child_field=hop.dest_field),
+                subquery=sub.ast,
+            )
+            return self._with_relationship(relationship, sub, entry)
+
+        first, second = related
+        q = self._new(
+            second.dest_schema,
+            AST(table=second.dest_schema, alias=relationship),
+            relationship,
+            Format(singular=second.cardinality == "one"),
+        )
+        sub = _as_query(cb(q))
+        for key in (first.source_field, first.dest_field, second.source_field, second.dest_field):
+            check(len(key) >= 1, "Invalid relationship")
+        entry = CorrelatedSubquery(
+            system=self._system,
+            correlation=Correlation(parent_field=first.source_field, child_field=first.dest_field),
+            hidden=True,
+            subquery=AST(
+                table=first.dest_schema,
+                alias=relationship,
+                related=(
+                    CorrelatedSubquery(
+                        system=self._system,
+                        correlation=Correlation(parent_field=second.source_field, child_field=second.dest_field),
+                        subquery=sub.ast,
+                    ),
+                ),
+            ),
+        )
+        return self._with_relationship(relationship, sub, entry)
+
+    def start[Q: Query[Any, Any]](self: Q, row: Mapping[str, Any], *, inclusive: bool = False) -> Q:
+        for column in row:
+            self._check_column(column)
+        return self._with(start=Bound(row=dict(row), exclusive=not inclusive))
+
+    def limit[Q: Query[Any, Any]](self: Q, limit: int | float) -> Q:
+        if limit < 0:
+            raise Exception("Limit must be non-negative")
+        if not (isinstance(limit, int | float) and limit == int(limit) and -(2**31) <= limit < 2**31):
+            raise Exception("Limit must be an integer")
+        if self._junction:
+            raise NotImplementedError(
+                "Limit is not supported in junction relationships yet. Junction relationship being limited: "
+                + self._junction
+            )
+        return self._with(limit=limit)
+
+    def order_by[Q: Query[Any, Any]](self: Q, field: C, direction: Direction) -> Q:
+        self._check_column(field)
+        if self._junction:
+            raise NotImplementedError(
+                "Order by is not supported in junction relationships yet. Junction relationship being ordered: "
+                + self._junction
+            )
+        return self._with(order_by=(*(self._ast.order_by or ()), (field, direction)))
+
+    def _exists(
+        self,
+        relationship: str,
+        cb: SubqueryFn | None,
+        *,
+        flip: bool | None = None,
+        scalar: bool | None = None,
+    ) -> Condition:
+        cb = cb or (lambda q: q)
+        related = self._relationship(relationship)
+        if len(related) == 1:
+            (hop,) = related
+            check(len(hop.source_field) >= 1, "Invalid relationship")
+            check(len(hop.dest_field) >= 1, "Invalid relationship")
+            sub = _as_query(
+                cb(self._new(hop.dest_schema, AST(table=hop.dest_schema, alias=f"{SUBQ_PREFIX}{relationship}"), None))
+            )
+            return CorrelatedSubqueryCondition(
+                related=CorrelatedSubquery(
+                    system=self._system,
+                    correlation=Correlation(parent_field=hop.source_field, child_field=hop.dest_field),
+                    subquery=sub.ast,
+                ),
+                op="EXISTS",
+                flip=flip,
+                scalar=scalar,
+            )
+
+        first, second = related
+        for key in (first.source_field, first.dest_field, second.source_field, second.dest_field):
+            check(len(key) >= 1, "Invalid relationship")
+        to_dest = _as_query(
+            cb(
+                self._new(
+                    second.dest_schema,
+                    AST(table=second.dest_schema, alias=f"{SUBQ_PREFIX}zhidden_{relationship}"),
+                    relationship,
+                )
+            )
+        )
+        return CorrelatedSubqueryCondition(
+            related=CorrelatedSubquery(
+                system=self._system,
+                correlation=Correlation(parent_field=first.source_field, child_field=first.dest_field),
+                subquery=AST(
+                    table=first.dest_schema,
+                    alias=f"{SUBQ_PREFIX}{relationship}",
+                    where=CorrelatedSubqueryCondition(
+                        related=CorrelatedSubquery(
+                            system=self._system,
+                            correlation=Correlation(parent_field=second.source_field, child_field=second.dest_field),
+                            subquery=to_dest.ast,
+                        ),
+                        op="EXISTS",
+                        flip=flip,
+                        scalar=scalar,
+                    ),
+                ),
+            ),
+            op="EXISTS",
+            flip=flip,
+        )
+
+    def expression_builder(self) -> ExpressionBuilder:
+        return ExpressionBuilder(self._exists, self._check_column)
+
+
+class OneQuery(Query[R, C]):
+    """A query `one()` narrowed to a single row. Its methods keep it singular."""
+
+
+def _as_query(q: object) -> AnyQuery:
+    check(isinstance(q, Query), "Expected QueryImpl instance")
+    assert isinstance(q, Query)
+    return q
+
+
+class Builder:
+    """`create_builder(schema).issue` starts a query on the `issue` table.
+
+    With `strict=True`, a column the table does not have is refused when the query is built, as
+    `UnknownColumnError`. Upstream refuses it only when the query endpoint maps the AST, failing the
+    whole batch, so strict mode is for catching mistakes in your own tests rather than for production
+    parity.
+    """
+
+    def __init__(self, schema: Schema, *, strict: bool = False) -> None:
+        self._schema = schema
+        self._strict = strict
+
+    def __getattr__(self, table: str) -> Query[Any, Any]:
+        return self.table(table)
+
+    def table(self, name: str) -> Query[Any, Any]:
+        if name not in self._schema.tables:
+            raise AttributeError(name)
+        return Query(self._schema, name, AST(table=name), strict=self._strict)
+
+
+def create_builder(schema: Schema, *, strict: bool = False) -> Builder:
+    return Builder(schema, strict=strict)
+
+
+__all__ = ["MISSING", "Builder", "OneQuery", "Query", "UnknownColumnError", "create_builder"]

zero_server/query/expression.py

@@ -0,0 +1,167 @@
+"""Conditions for `Query.where`: `cmp`, `and_`, `or_`, `not_` and `exists`.
+
+Ported from rocicorp/mono `packages/zql/src/query/expression.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+"""
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any, Final
+
+from zero_server.protocol.ast import (
+    ColumnReference,
+    Condition,
+    Conjunction,
+    CorrelatedSubqueryCondition,
+    Disjunction,
+    LiteralReference,
+    Parameter,
+    SimpleCondition,
+    SimpleOperator,
+)
+
+if TYPE_CHECKING:
+    from zero_server.query.builder import Query
+
+MISSING: Final[Any] = object()
+"""Marks an argument the caller left out, which upstream tells apart from an explicit `undefined`."""
+
+TRUE: Final[Condition] = Conjunction(conditions=())
+FALSE: Final[Condition] = Disjunction(conditions=())
+
+_NEGATED: Final[dict[str, str]] = {
+    "=": "!=",
+    "!=": "=",
+    "<": ">=",
+    ">": "<=",
+    ">=": "<",
+    "<=": ">",
+    "IN": "NOT IN",
+    "NOT IN": "IN",
+    "LIKE": "NOT LIKE",
+    "NOT LIKE": "LIKE",
+    "ILIKE": "NOT ILIKE",
+    "NOT ILIKE": "ILIKE",
+    "IS": "IS NOT",
+    "IS NOT": "IS",
+    "EXISTS": "NOT EXISTS",
+    "NOT EXISTS": "EXISTS",
+}
+
+
+def _position(value: Any) -> LiteralReference | Parameter:
+    return value if isinstance(value, Parameter) else LiteralReference(value=value)
+
+
+def cmp(field: str, op_or_value: Any, value: Any = MISSING) -> Condition:
+    """`cmp(field, value)` compares with `=`; `cmp(field, op, value)` with `op`."""
+    if value is MISSING:
+        op, actual = "=", op_or_value
+    else:
+        op, actual = op_or_value, value
+    return SimpleCondition(op=op, left=ColumnReference(name=field), right=_position(actual))
+
+
+def _is_always_true(condition: Condition) -> bool:
+    return isinstance(condition, Conjunction) and not condition.conditions
+
+
+def _is_always_false(condition: Condition) -> bool:
+    return isinstance(condition, Disjunction) and not condition.conditions
+
+
+def and_(*conditions: Condition | None) -> Condition:
+    expressions = [c for c in conditions if c is not None and not _is_always_true(c)]
+    if len(expressions) == 1:
+        return expressions[0]
+    if any(_is_always_false(c) for c in expressions):
+        return FALSE
+    return Conjunction(conditions=tuple(expressions))
+
+
+def or_(*conditions: Condition | None) -> Condition:
+    expressions = [c for c in conditions if c is not None and not _is_always_false(c)]
+    if len(expressions) == 1:
+        return expressions[0]
+    if any(_is_always_true(c) for c in expressions):
+        return TRUE
+    return Disjunction(conditions=tuple(expressions))
+
+
+def not_(expression: Condition) -> Condition:
+    match expression:
+        case Conjunction():
+            return Disjunction(conditions=tuple(not_(c) for c in expression.conditions))
+        case Disjunction():
+            return Conjunction(conditions=tuple(not_(c) for c in expression.conditions))
+        case CorrelatedSubqueryCondition():
+            return CorrelatedSubqueryCondition(
+                related=expression.related,
+                op=_NEGATED[expression.op],  # ty: ignore[invalid-argument-type]
+                flip=expression.flip,
+                scalar=expression.scalar,
+            )
+        case _:
+            return SimpleCondition(
+                op=_NEGATED[expression.op],  # ty: ignore[invalid-argument-type]
+                left=expression.left,
+                right=expression.right,
+            )
+
+
+def _flatten(kind: str, conditions: Sequence[Condition]) -> list[Condition]:
+    out: list[Condition] = []
+    for c in conditions:
+        if isinstance(c, Conjunction | Disjunction) and c.type == kind:
+            out.extend(c.conditions)
+        else:
+            out.append(c)
+    return out
+
+
+def simplify_condition(c: Condition) -> Condition:
+    if isinstance(c, SimpleCondition | CorrelatedSubqueryCondition):
+        return c
+    if len(c.conditions) == 1:
+        return simplify_condition(c.conditions[0])
+    conditions = _flatten(c.type, [simplify_condition(x) for x in c.conditions])
+    if c.type == "and" and any(_is_always_false(x) for x in conditions):
+        return FALSE
+    if c.type == "or" and any(_is_always_true(x) for x in conditions):
+        return TRUE
+    return type(c)(conditions=tuple(conditions))
+
+
+type ExistsFn = Callable[..., Condition]
+
+
+class ExpressionBuilder:
+    """What a `where` callback receives. `and`, `or` and `not` gain a trailing underscore in Python."""
+
+    def __init__(self, exists: ExistsFn, check_column: Callable[[str], None] | None = None) -> None:
+        self._exists = exists
+        self._check_column = check_column or (lambda _column: None)
+
+    @property
+    def eb(self) -> "ExpressionBuilder":
+        return self
+
+    def cmp(self, field: str, op_or_value: Any, value: Any = MISSING) -> Condition:
+        self._check_column(field)
+        return cmp(field, op_or_value, value)
+
+    def cmp_lit(self, left: Any, op: SimpleOperator, right: Any) -> Condition:
+        return SimpleCondition(op=op, left=_position(left), right=_position(right))
+
+    and_ = staticmethod(and_)
+    or_ = staticmethod(or_)
+    not_ = staticmethod(not_)
+
+    def exists(
+        self,
+        relationship: str,
+        cb: "Callable[[Query], Query] | None" = None,
+        *,
+        flip: bool | None = None,
+        scalar: bool | None = None,
+    ) -> Condition:
+        return self._exists(relationship, cb, flip=flip, scalar=scalar)