zero-server 0.0.1__py3-none-any.whl

zero_server/protocol/ast.py

@@ -0,0 +1,342 @@
+"""The ZQL AST: what a query endpoint returns for each query zero-cache asks it to transform.
+
+Ported from rocicorp/mono `packages/zero-protocol/src/ast.ts`, `data.ts` and `primary-key.ts` at
+zero/v1.10.0 (905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+
+The AST carries server names: `map_ast` maps a client-named AST through the schema's name mapper before
+it goes on the wire, as `handleQueryRequest` does upstream.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Annotated, Literal, Protocol
+
+from pydantic import Field, StrictBool, StrictStr
+
+from zero_server.protocol.wire import Number, StrictWireModel
+from zero_server.shared.asserts import AssertionFailedError, check
+from zero_server.shared.js import js_sort, js_string
+from zero_server.shared.json import JSONValue
+
+SUBQ_PREFIX = "zsubq_"
+
+type System = Literal["permissions", "client", "test"]
+type Direction = Literal["asc", "desc"]
+type OrderPart = tuple[StrictStr, Direction]
+type Ordering = tuple[OrderPart, ...]
+
+type EqualityOp = Literal["=", "!=", "IS", "IS NOT"]
+type OrderOp = Literal["<", ">", "<=", ">="]
+type LikeOp = Literal["LIKE", "NOT LIKE", "ILIKE", "NOT ILIKE"]
+type InOp = Literal["IN", "NOT IN"]
+type SimpleOperator = Literal[
+    "=", "!=", "IS", "IS NOT", "<", ">", "<=", ">=", "LIKE", "NOT LIKE", "ILIKE", "NOT ILIKE", "IN", "NOT IN"
+]
+type CorrelatedSubqueryConditionOperator = Literal["EXISTS", "NOT EXISTS"]
+
+type Scalar = StrictStr | Number | StrictBool
+type LiteralValue = Scalar | tuple[Scalar, ...] | None
+
+type Value = JSONValue
+"""A row value. Upstream also allows `undefined`, which it treats as `null`."""
+type Row = dict[str, Value]
+
+type PrimaryKey = tuple[StrictStr, ...]
+type CompoundKey = Annotated[tuple[StrictStr, ...], Field(min_length=1)]
+
+
+class LiteralReference(StrictWireModel):
+    nullable = frozenset({"value"})
+
+    type: Literal["literal"] = "literal"
+    value: LiteralValue
+
+
+class ColumnReference(StrictWireModel):
+    type: Literal["column"] = "column"
+    name: StrictStr
+
+
+class Parameter(StrictWireModel):
+    """A value resolved at runtime: the caller's auth data, or a row before a mutation touched it."""
+
+    type: Literal["static"] = "static"
+    anchor: Literal["authData", "preMutationRow"]
+    field: StrictStr | tuple[StrictStr, ...]
+
+
+type ValuePosition = Annotated[LiteralReference | ColumnReference | Parameter, Field(discriminator="type")]
+
+
+class SimpleCondition(StrictWireModel):
+    type: Literal["simple"] = "simple"
+    op: SimpleOperator
+    left: ValuePosition
+    right: Annotated[Parameter | LiteralReference, Field(discriminator="type")]
+
+
+class Conjunction(StrictWireModel):
+    type: Literal["and"] = "and"
+    conditions: tuple[Condition, ...]
+
+
+class Disjunction(StrictWireModel):
+    type: Literal["or"] = "or"
+    conditions: tuple[Condition, ...]
+
+
+class CorrelatedSubqueryCondition(StrictWireModel):
+    type: Literal["correlatedSubquery"] = "correlatedSubquery"
+    related: CorrelatedSubquery
+    op: CorrelatedSubqueryConditionOperator
+    flip: StrictBool | None = None
+    scalar: StrictBool | None = None
+
+
+type Condition = Annotated[
+    SimpleCondition | Conjunction | Disjunction | CorrelatedSubqueryCondition, Field(discriminator="type")
+]
+
+
+class Correlation(StrictWireModel):
+    parent_field: CompoundKey = Field(alias="parentField")
+    child_field: CompoundKey = Field(alias="childField")
+
+
+class CorrelatedSubquery(StrictWireModel):
+    correlation: Correlation
+    subquery: AST
+    system: System | None = None
+    # A hop the client never sees, such as the junction table of a many-to-many relationship.
+    hidden: StrictBool | None = None
+
+
+class Bound(StrictWireModel):
+    row: Row
+    exclusive: StrictBool
+
+
+class AST(StrictWireModel):
+    schema_: StrictStr | None = Field(default=None, alias="schema")
+    table: StrictStr
+    # Set on every subquery, to tell apart two subqueries over the same table.
+    alias: StrictStr | None = None
+    where: Condition | None = None
+    related: tuple[CorrelatedSubquery, ...] | None = None
+    limit: Number | None = None
+    order_by: Ordering | None = Field(default=None, alias="orderBy")
+    start: Bound | None = None
+
+
+for _model in (Conjunction, Disjunction, CorrelatedSubqueryCondition, CorrelatedSubquery, AST):
+    _model.model_rebuild()
+
+
+class NameMapper(Protocol):
+    def table_name(self, table: str, /) -> str: ...
+
+    def column_name(self, table: str, column: str, /) -> str: ...
+
+
+@dataclass(frozen=True)
+class _Transform:
+    table_name: Callable[[str], str]
+    column_name: Callable[[str, str], str]
+    related: Callable[[list[CorrelatedSubquery]], Sequence[CorrelatedSubquery]]
+    where: Callable[[Condition], Condition | None]
+    conditions: Callable[[list[Condition]], Sequence[Condition]]
+
+
+def _key(transform: _Transform, table: str, key: Sequence[str]) -> tuple[str, ...]:
+    mapped = tuple(transform.column_name(table, column) for column in key)
+    check(len(mapped) >= 1, "Expected non-empty array for compound key")
+    return mapped
+
+
+def _transform_ast(ast: AST, transform: _Transform) -> AST:
+    def col(column: str) -> str:
+        return transform.column_name(ast.table, column)
+
+    where = transform.where(ast.where) if ast.where is not None else None
+    related = (
+        tuple(
+            transform.related(
+                [
+                    CorrelatedSubquery(
+                        correlation=Correlation(
+                            parent_field=_key(transform, ast.table, r.correlation.parent_field),
+                            child_field=_key(transform, r.subquery.table, r.correlation.child_field),
+                        ),
+                        hidden=r.hidden,
+                        subquery=_transform_ast(r.subquery, transform),
+                        system=r.system,
+                    )
+                    for r in ast.related
+                ]
+            )
+        )
+        if ast.related is not None
+        else None
+    )
+    return AST(
+        schema=ast.schema_,
+        table=transform.table_name(ast.table),
+        alias=ast.alias,
+        where=_transform_where(where, ast.table, transform) if where is not None else None,
+        related=related,
+        start=(
+            Bound(row={col(name): value for name, value in ast.start.row.items()}, exclusive=ast.start.exclusive)
+            if ast.start is not None
+            else None
+        ),
+        limit=ast.limit,
+        orderBy=tuple((col(name), direction) for name, direction in ast.order_by) if ast.order_by is not None else None,
+    )
+
+
+def _transform_where(where: Condition, table: str, transform: _Transform) -> Condition:
+    match where:
+        case SimpleCondition(left=ColumnReference(name=name)):
+            return where.model_copy(update={"left": ColumnReference(name=transform.column_name(table, name))})
+        case SimpleCondition():
+            return where
+        case CorrelatedSubqueryCondition(related=related):
+            mapped = related.model_copy(
+                update={
+                    "correlation": Correlation(
+                        parent_field=_key(transform, table, related.correlation.parent_field),
+                        child_field=_key(transform, related.subquery.table, related.correlation.child_field),
+                    ),
+                    "subquery": _transform_ast(related.subquery, transform),
+                }
+            )
+            return where.model_copy(update={"related": mapped})
+        case _:
+            conditions = tuple(transform.conditions([_transform_where(c, table, transform) for c in where.conditions]))
+            return type(where)(conditions=conditions)
+
+
+def map_ast(ast: AST, mapper: NameMapper) -> AST:
+    """Rename every table and column in `ast` through `mapper`, client names to server names upstream."""
+    return _transform_ast(ast, _mapping(mapper))
+
+
+def map_condition(condition: Condition, table: str, mapper: NameMapper) -> Condition:
+    return _transform_where(condition, table, _mapping(mapper))
+
+
+def _mapping(mapper: NameMapper) -> _Transform:
+    return _Transform(
+        table_name=mapper.table_name,
+        column_name=mapper.column_name,
+        related=lambda r: r,
+        where=lambda w: w,
+        conditions=lambda c: c,
+    )
+
+
+def normalize_ast(ast: AST) -> AST:
+    """The canonical form zero-cache hashes: flattened conditions, sorted conditions and subqueries."""
+    return _transform_ast(
+        ast,
+        _Transform(
+            table_name=lambda t: t,
+            column_name=lambda _t, c: c,
+            related=lambda r: js_sort(r, _cmp_related),
+            where=_flattened,
+            conditions=lambda c: js_sort(c, _cmp_condition),
+        ),
+    )
+
+
+def _utf8(value: str) -> bytes:
+    return value.encode("utf-8", "surrogatepass")
+
+
+def _cmp(a: object, b: object) -> int:
+    return (a > b) - (a < b)  # ty: ignore[unsupported-operator]
+
+
+def _cmp_utf8(a: str, b: str) -> int:
+    return _cmp(_utf8(a), _utf8(b))
+
+
+def _cmp_value_position(
+    a: LiteralReference | ColumnReference | Parameter, b: LiteralReference | ColumnReference | Parameter
+) -> int:
+    if a.type != b.type:
+        return _cmp_utf8(a.type, b.type)
+    match a, b:
+        case LiteralReference(), LiteralReference():
+            return _cmp_utf8(js_string(a.value), js_string(b.value))
+        case ColumnReference(), ColumnReference():
+            return _cmp_utf8(a.name, b.name)
+        case _:
+            raise ValueError("Static parameters should be resolved before normalization")
+
+
+def _cmp_related(a: CorrelatedSubquery, b: CorrelatedSubquery) -> int:
+    return _cmp_utf8(_must(a.subquery.alias), _must(b.subquery.alias))
+
+
+def _must(alias: str | None) -> str:
+    if alias is None:
+        raise AssertionFailedError("Unexpected undefined value")
+    return alias
+
+
+def _cmp_optional_bool(a: bool | None, b: bool | None) -> int:
+    def rank(v: bool | None) -> int:
+        return 0 if v is None else 2 if v else 1
+
+    return rank(a) - rank(b)
+
+
+def _cmp_condition(a: Condition, b: Condition) -> int:
+    if isinstance(a, SimpleCondition):
+        if not isinstance(b, SimpleCondition):
+            return -1
+        return _cmp_value_position(a.left, b.left) or _cmp_utf8(a.op, b.op) or _cmp_value_position(a.right, b.right)
+    if isinstance(b, SimpleCondition):
+        return 1
+    if isinstance(a, CorrelatedSubqueryCondition):
+        if not isinstance(b, CorrelatedSubqueryCondition):
+            return -1
+        return (
+            _cmp_related(a.related, b.related)
+            or _cmp_utf8(a.op, b.op)
+            or _cmp_optional_bool(a.flip, b.flip)
+            or _cmp_optional_bool(a.scalar, b.scalar)
+        )
+    if isinstance(b, CorrelatedSubqueryCondition):
+        # Upstream returns -1 here too, so a subquery and a compound condition each sort first.
+        return -1
+    by_type = _cmp_utf8(a.type, b.type)
+    if by_type:
+        return by_type
+    for left, right in zip(a.conditions, b.conditions, strict=False):
+        by_condition = _cmp_condition(left, right)
+        if by_condition:
+            return by_condition
+    return len(a.conditions) - len(b.conditions)
+
+
+def _flattened(condition: Condition) -> Condition | None:
+    if isinstance(condition, SimpleCondition | CorrelatedSubqueryCondition):
+        return condition
+    flat: list[Condition | None] = []
+    for c in condition.conditions:
+        if isinstance(c, Conjunction | Disjunction) and c.type == condition.type:
+            flat.extend(_flattened(inner) for inner in c.conditions)
+        else:
+            flat.append(_flattened(c))
+    conditions = [c for c in flat if c is not None]
+    match len(conditions):
+        case 0:
+            return None
+        case 1:
+            return conditions[0]
+        case _:
+            return type(condition)(conditions=tuple(conditions))

zero_server/protocol/custom_queries.py

@@ -0,0 +1,51 @@
+"""What zero-cache POSTs to a query endpoint, and what each query becomes.
+
+Ported from rocicorp/mono `packages/zero-protocol/src/custom-queries.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+"""
+
+from typing import Literal
+
+from pydantic import StrictStr
+
+from zero_server.protocol.ast import AST
+from zero_server.protocol.wire import StrictWireModel, WireModel
+from zero_server.shared.json import JSONValue
+
+
+class TransformRequestQuery(StrictWireModel):
+    """Parsed in upstream's default (strict) mode, so an undeclared key fails the whole request."""
+
+    id: StrictStr
+    name: StrictStr
+    args: list[JSONValue]
+
+
+type TransformRequestBody = list[TransformRequestQuery]
+type TransformRequestMessage = tuple[Literal["transform"], TransformRequestBody]
+
+
+class TransformedQuery(WireModel):
+    id: StrictStr
+    name: StrictStr
+    ast: AST
+
+
+class AppErroredQuery(WireModel):
+    error: Literal["app"] = "app"
+    id: StrictStr
+    name: StrictStr
+    message: StrictStr | None = None
+    details: JSONValue | None = None
+
+
+class ParseErroredQuery(WireModel):
+    error: Literal["parse"] = "parse"
+    id: StrictStr
+    name: StrictStr
+    message: StrictStr
+    details: JSONValue | None = None
+
+
+type ErroredQuery = AppErroredQuery | ParseErroredQuery
+type TransformResponseBody = list[TransformedQuery | ErroredQuery]

zero_server/protocol/error.py

@@ -0,0 +1,119 @@
+"""Error kinds, origins and reasons, and the bodies of a failed push or transform.
+
+Ported from rocicorp/mono `packages/zero-protocol/src/error.ts`, `error-kind-enum.ts`,
+`error-origin-enum.ts` and `error-reason-enum.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+"""
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import Field, StrictStr
+
+from zero_server.protocol.mutation_id import MutationID
+from zero_server.protocol.wire import Number, WireModel
+from zero_server.shared.json import JSONValue
+
+
+class ErrorKind(StrEnum):
+    AUTH_INVALIDATED = "AuthInvalidated"
+    CLIENT_NOT_FOUND = "ClientNotFound"
+    INVALID_CONNECTION_REQUEST = "InvalidConnectionRequest"
+    INVALID_CONNECTION_REQUEST_BASE_COOKIE = "InvalidConnectionRequestBaseCookie"
+    INVALID_CONNECTION_REQUEST_LAST_MUTATION_ID = "InvalidConnectionRequestLastMutationID"
+    INVALID_CONNECTION_REQUEST_CLIENT_DELETED = "InvalidConnectionRequestClientDeleted"
+    INVALID_MESSAGE = "InvalidMessage"
+    INVALID_PUSH = "InvalidPush"
+    PUSH_FAILED = "PushFailed"
+    MUTATION_FAILED = "MutationFailed"
+    MUTATION_RATE_LIMITED = "MutationRateLimited"
+    REBALANCE = "Rebalance"
+    REHOME = "Rehome"
+    TRANSFORM_FAILED = "TransformFailed"
+    UNAUTHORIZED = "Unauthorized"
+    VERSION_NOT_SUPPORTED = "VersionNotSupported"
+    SCHEMA_VERSION_NOT_SUPPORTED = "SchemaVersionNotSupported"
+    SERVER_OVERLOADED = "ServerOverloaded"
+    INTERNAL = "Internal"
+
+
+class ErrorOrigin(StrEnum):
+    CLIENT = "client"
+    SERVER = "server"
+    ZERO_CACHE = "zeroCache"
+
+
+class ErrorReason(StrEnum):
+    DATABASE = "database"
+    PARSE = "parse"
+    OUT_OF_ORDER_MUTATION = "oooMutation"
+    UNSUPPORTED_PUSH_VERSION = "unsupportedPushVersion"
+    INTERNAL = "internal"
+    HTTP = "http"
+    TIMEOUT = "timeout"
+
+
+type ServerPushFailedReason = Literal[
+    ErrorReason.DATABASE,
+    ErrorReason.PARSE,
+    ErrorReason.OUT_OF_ORDER_MUTATION,
+    ErrorReason.UNSUPPORTED_PUSH_VERSION,
+    ErrorReason.INTERNAL,
+]
+type ServerTransformFailedReason = Literal[ErrorReason.DATABASE, ErrorReason.PARSE, ErrorReason.INTERNAL]
+type ZeroCacheFailedReason = Literal[ErrorReason.TIMEOUT, ErrorReason.PARSE, ErrorReason.INTERNAL]
+
+
+class _PushFailedBase(WireModel):
+    kind: Literal[ErrorKind.PUSH_FAILED] = ErrorKind.PUSH_FAILED
+    details: JSONValue | None = None
+    # The mutations that went unprocessed, which can be a tail of the request's.
+    mutation_ids: list[MutationID] = Field(alias="mutationIDs")
+    message: StrictStr
+
+
+class ServerPushFailed(_PushFailedBase):
+    origin: Literal[ErrorOrigin.SERVER] = ErrorOrigin.SERVER
+    reason: ServerPushFailedReason
+
+
+class ZeroCachePushHTTPFailed(_PushFailedBase):
+    origin: Literal[ErrorOrigin.ZERO_CACHE]
+    reason: Literal[ErrorReason.HTTP]
+    status: Number
+    body_preview: StrictStr | None = Field(default=None, alias="bodyPreview")
+
+
+class ZeroCachePushFailed(_PushFailedBase):
+    origin: Literal[ErrorOrigin.ZERO_CACHE]
+    reason: ZeroCacheFailedReason
+
+
+type PushFailedBody = ServerPushFailed | ZeroCachePushHTTPFailed | ZeroCachePushFailed
+
+
+class _TransformFailedBase(WireModel):
+    kind: Literal[ErrorKind.TRANSFORM_FAILED] = ErrorKind.TRANSFORM_FAILED
+    details: JSONValue | None = None
+    query_ids: list[StrictStr] = Field(alias="queryIDs")
+    message: StrictStr
+
+
+class ServerTransformFailed(_TransformFailedBase):
+    origin: Literal[ErrorOrigin.SERVER] = ErrorOrigin.SERVER
+    reason: ServerTransformFailedReason
+
+
+class ZeroCacheTransformHTTPFailed(_TransformFailedBase):
+    origin: Literal[ErrorOrigin.ZERO_CACHE]
+    reason: Literal[ErrorReason.HTTP]
+    status: Number
+    body_preview: StrictStr | None = Field(default=None, alias="bodyPreview")
+
+
+class ZeroCacheTransformFailed(_TransformFailedBase):
+    origin: Literal[ErrorOrigin.ZERO_CACHE]
+    reason: ZeroCacheFailedReason
+
+
+type TransformFailedBody = ServerTransformFailed | ZeroCacheTransformHTTPFailed | ZeroCacheTransformFailed

zero_server/protocol/mutate_server.py

@@ -0,0 +1,33 @@
+"""The mutate endpoint's response and query string.
+
+Ported from rocicorp/mono `packages/zero-protocol/src/mutate-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.error import PushFailedBody
+from zero_server.protocol.mutation import MutationResponse
+from zero_server.protocol.wire import WireModel
+
+
+class MutateSuccess(WireModel):
+    """`user_id` is reported to zero-cache only when the caller set it, `None` included."""
+
+    nullable = frozenset({"user_id"})
+
+    kind: Literal["MutateResponse"] = "MutateResponse"
+    user_id: StrictStr | None = Field(default=None, alias="userID")
+    mutations: list[MutationResponse]
+
+
+type MutateResponse = MutateSuccess | PushFailedBody
+
+
+class MutateParams(WireModel):
+    """The query string zero-cache appends: the upstream schema holding its bookkeeping, and the app."""
+
+    schema_: StrictStr = Field(alias="schema")
+    app_id: StrictStr = Field(alias="appID")

zero_server/protocol/mutation.py

@@ -0,0 +1,127 @@
+"""Mutations as a push carries them, and the result recorded for each.
+
+Ported from rocicorp/mono `packages/zero-protocol/src/mutation.ts` and `mutation-type-enum.ts` at
+zero/v1.10.0 (905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+"""
+
+from typing import Annotated, Literal
+
+from pydantic import Field, StrictBool, StrictStr
+
+from zero_server.protocol.ast import PrimaryKey, Row
+from zero_server.protocol.mutation_id import MutationID
+from zero_server.protocol.wire import Number, StrictWireModel, WireModel
+from zero_server.shared.json import JSONValue
+
+CRUD_MUTATION_NAME = "_zero_crud"
+
+# zero-cache sends this to delete results its clients have acknowledged. It is not a client mutation.
+CLEANUP_RESULTS_MUTATION_NAME = "_zero_cleanupResults"
+
+type NonEmptyKey = Annotated[PrimaryKey, Field(min_length=1)]
+type PrimaryKeyValue = StrictStr | Number | StrictBool
+
+
+class CleanupResultsLegacyArg(StrictWireModel):
+    """The oldest form, with no `type`. Treated as `single`."""
+
+    client_group_id: StrictStr = Field(alias="clientGroupID")
+    client_id: StrictStr = Field(alias="clientID")
+    up_to_mutation_id: Number = Field(alias="upToMutationID")
+
+
+class CleanupResultsSingleArg(StrictWireModel):
+    type: Literal["single"]
+    client_group_id: StrictStr = Field(alias="clientGroupID")
+    client_id: StrictStr = Field(alias="clientID")
+    up_to_mutation_id: Number = Field(alias="upToMutationID")
+
+
+class CleanupResultsBulkArg(StrictWireModel):
+    type: Literal["bulk"]
+    client_group_id: StrictStr = Field(alias="clientGroupID")
+    client_ids: Annotated[list[StrictStr], Field(min_length=1)] = Field(alias="clientIDs")
+
+
+type CleanupResultsArg = CleanupResultsLegacyArg | CleanupResultsSingleArg | CleanupResultsBulkArg
+
+
+class InsertOp(WireModel):
+    op: Literal["insert"]
+    table_name: StrictStr = Field(alias="tableName")
+    primary_key: NonEmptyKey = Field(alias="primaryKey")
+    value: Row
+
+
+class UpsertOp(WireModel):
+    op: Literal["upsert"]
+    table_name: StrictStr = Field(alias="tableName")
+    primary_key: NonEmptyKey = Field(alias="primaryKey")
+    value: Row
+
+
+class UpdateOp(WireModel):
+    op: Literal["update"]
+    table_name: StrictStr = Field(alias="tableName")
+    primary_key: NonEmptyKey = Field(alias="primaryKey")
+    value: Row
+
+
+class DeleteOp(WireModel):
+    op: Literal["delete"]
+    table_name: StrictStr = Field(alias="tableName")
+    primary_key: NonEmptyKey = Field(alias="primaryKey")
+    value: dict[str, PrimaryKeyValue]
+
+
+type CRUDOp = Annotated[InsertOp | UpsertOp | UpdateOp | DeleteOp, Field(discriminator="op")]
+
+
+class CRUDMutationArg(WireModel):
+    ops: list[CRUDOp]
+
+
+class CRUDMutation(WireModel):
+    type: Literal["crud"]
+    id: Number
+    client_id: StrictStr = Field(alias="clientID")
+    name: Literal["_zero_crud"]
+    args: tuple[CRUDMutationArg]
+    timestamp: Number
+
+
+class CustomMutation(WireModel):
+    type: Literal["custom"]
+    id: Number
+    client_id: StrictStr = Field(alias="clientID")
+    name: StrictStr
+    args: list[JSONValue]
+    timestamp: Number
+
+
+type Mutation = Annotated[CRUDMutation | CustomMutation, Field(discriminator="type")]
+
+
+class MutationOk(WireModel):
+    # Whatever the mutator returned, if anything.
+    data: JSONValue | None = None
+
+
+class MutationAppError(WireModel):
+    error: Literal["app"] = "app"
+    message: StrictStr | None = None
+    details: JSONValue | None = None
+
+
+class MutationZeroError(WireModel):
+    # `oooMutation` is reported as a failed push now; the literal stays for older peers.
+    error: Literal["oooMutation", "alreadyProcessed"]
+    details: JSONValue | None = None
+
+
+type MutationResult = MutationAppError | MutationZeroError | MutationOk
+
+
+class MutationResponse(WireModel):
+    id: MutationID
+    result: MutationResult

zero_server/protocol/mutation_id.py

@@ -0,0 +1,12 @@
+"""Ported from rocicorp/mono `packages/zero-protocol/src/mutation-id.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+"""
+
+from pydantic import Field, StrictStr
+
+from zero_server.protocol.wire import Number, WireModel
+
+
+class MutationID(WireModel):
+    id: Number
+    client_id: StrictStr = Field(alias="clientID")