zero-server 0.0.1__py3-none-any.whl

zero_server/__init__.py

@@ -0,0 +1,36 @@
+"""Community Python server SDK for Rocicorp Zero. Not affiliated with Rocicorp.
+
+The SQLAlchemy transaction provider lives in `zero_server.server.adapters.sqlalchemy` and needs the
+`zero-server[sqlalchemy]` extra.
+"""
+
+from zero_server.mutators import define_mutator, define_mutators, get_mutator, must_get_mutator
+from zero_server.protocol.application_error import ApplicationError
+from zero_server.query.builder import Query, create_builder
+from zero_server.query.registry import QueryParseError, define_queries, define_query, get_query, must_get_query
+from zero_server.schema import Schema, load_schema
+from zero_server.server.process_mutations import handle_mutate_request
+from zero_server.server.process_queries import handle_query_request
+from zero_server.server.push_processor import PushProcessor
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "ApplicationError",
+    "PushProcessor",
+    "Query",
+    "QueryParseError",
+    "Schema",
+    "create_builder",
+    "define_mutator",
+    "define_mutators",
+    "define_queries",
+    "define_query",
+    "get_mutator",
+    "get_query",
+    "handle_mutate_request",
+    "handle_query_request",
+    "load_schema",
+    "must_get_mutator",
+    "must_get_query",
+]

zero_server/codegen.py

@@ -0,0 +1,133 @@
+"""Typed Python for a Zero schema: row types per table, and a builder and `tx.mutate` that use them.
+
+    zero-server codegen schema.json -o zero_schema.py
+
+`schema.json` is `JSON.stringify(schema)` of the TypeScript `schema.ts`. The generated module has, per
+table, a `TypedDict` for a row (`Issue`), for an insert (`IssueInsert`, optional columns may be left
+out), for an update (`IssueUpdate`, the key plus any columns) and for a delete (`IssueKey`), and a
+`Literal` of its column names (`IssueColumn`). Its `create_builder` returns queries typed by those rows
+and columns, and `mutate(tx)` is `tx.mutate` typed the same way. Rows of a `related()` relationship
+come back nested under each row but are not part of the row type.
+"""
+
+import argparse
+import json
+import keyword
+import re
+import sys
+from pathlib import Path
+
+from zero_server.schema import ColumnSchema, Schema, TableSchema, load_schema
+
+_TYPES = {"string": "str", "number": "float", "boolean": "bool", "null": "None", "json": "Any"}
+
+
+def _class_name(table: str) -> str:
+    parts = re.split(r"[^0-9A-Za-z]+", table)
+    name = "".join(part[:1].upper() + part[1:] for part in parts if part)
+    if not name or name[0].isdigit():
+        name = f"Table{name}"
+    return name
+
+
+def _is_identifier(name: str) -> bool:
+    return name.isidentifier() and not keyword.iskeyword(name)
+
+
+def _value_type(column: ColumnSchema) -> str:
+    base = _TYPES[column.type]
+    return f"{base} | None" if column.optional and base not in ("Any", "None") else base
+
+
+def _typed_dict(name: str, fields: list[tuple[str, str, bool]]) -> str:
+    """A TypedDict, in class syntax when every key is an identifier, else in functional syntax.
+
+    Never empty: every table has a primary key, which all four row types include.
+    """
+    if all(_is_identifier(key) for key, _, _ in fields):
+        lines = [f"    {key}: {f'NotRequired[{t}]' if not required else t}" for key, t, required in fields]
+        return f"class {name}(TypedDict):\n" + "\n".join(lines) + "\n"
+    items = ", ".join(f"{json.dumps(key)}: {f'NotRequired[{t}]' if not required else t}" for key, t, required in fields)
+    return f"{name} = TypedDict({json.dumps(name)}, {{{items}}})\n"
+
+
+def _table(name: str, table: TableSchema, used: set[str]) -> tuple[str, str]:
+    """The table's type definitions, and the class name they were given."""
+    cls = _class_name(name)
+    while cls in used:
+        cls += "_"
+    used.add(cls)
+    pk = set(table.primary_key)
+    columns = list(table.columns.items())
+    row = [(c, _value_type(s), True) for c, s in columns]
+    insert = [(c, _value_type(s), c in pk or not s.optional) for c, s in columns]
+    update = [(c, _value_type(s), c in pk) for c, s in columns]
+    key = [(c, _value_type(table.columns[c]), True) for c in table.primary_key]
+    column_names = ", ".join(json.dumps(c) for c, _ in columns)
+    out = [
+        f"type {cls}Column = Literal[{column_names}]\n",
+        _typed_dict(cls, row),
+        _typed_dict(f"{cls}Insert", insert),
+        _typed_dict(f"{cls}Update", update),
+        _typed_dict(f"{cls}Key", key),
+    ]
+    return "\n\n".join(out), cls
+
+
+def generate(schema: Schema, source: str = "schema.json") -> str:
+    used: set[str] = set()
+    definitions: list[str] = []
+    builder: list[str] = []
+    mutate: list[str] = []
+    for name, table in schema.tables.items():
+        types, cls = _table(name, table, used)
+        definitions.append(types)
+        if _is_identifier(name):
+            builder.append(
+                f"    @property\n    def {name}(self) -> Query[{cls}, {cls}Column]:\n"
+                f"        return self.table({json.dumps(name)})\n"
+            )
+            crud = f"TableCRUD[{cls}Insert, {cls}Update, {cls}Key]"
+            mutate.append(f"    @property\n    def {name}(self) -> {crud}: ...\n")
+    header = f'''"""Types for the Zero schema in {source}. Generated by `zero-server codegen`; do not edit."""
+
+from typing import Any, Literal, NotRequired, Protocol, TypedDict, cast
+
+from zero_server.query.builder import Builder as _Builder
+from zero_server.query.builder import Query
+from zero_server.schema import Schema
+from zero_server.server.crud import TableCRUD
+from zero_server.server.transaction import ServerTransaction
+'''
+    body = "\n\n".join(definitions)
+    builder_class = "class Builder(_Builder):\n" + ("\n".join(builder) if builder else "    pass\n")
+    mutate_class = "class Mutate(Protocol):\n" + ("\n".join(mutate) if mutate else "    pass\n")
+    footer = '''def create_builder(schema: Schema, *, strict: bool = False) -> Builder:
+    return Builder(schema, strict=strict)
+
+
+def mutate(tx: ServerTransaction[Any]) -> Mutate:
+    """`tx.mutate`, typed by this schema."""
+    return cast(Mutate, tx.mutate)
+'''
+    # One blank line after the imports, two between definitions: what ruff's formatter and isort keep.
+    return header + "\n" + "\n\n".join([body, builder_class, mutate_class, footer]).rstrip() + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="zero-server")
+    commands = parser.add_subparsers(dest="command", required=True)
+    codegen = commands.add_parser("codegen", help="generate Python types for a schema")
+    codegen.add_argument("schema", type=Path, help="the JSON of the TypeScript schema")
+    codegen.add_argument("-o", "--output", type=Path, help="write here instead of to stdout")
+    args = parser.parse_args(argv)
+    code = generate(load_schema(args.schema), args.schema.name)
+    if args.output is None:
+        sys.stdout.write(code)
+    else:
+        args.output.write_text(code)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - the `zero-server` script calls `main` directly
+    sys.exit(main())

zero_server/integrations/__init__.py

@@ -0,0 +1 @@
+"""Ready-made endpoints for web frameworks."""

zero_server/integrations/starlette.py

@@ -0,0 +1,115 @@
+"""`/query` and `/mutate` as Starlette routes. Needs the `zero-server[starlette]` extra.
+
+    app = Starlette(routes=zero_routes(
+        schema=schema, database=db, queries=queries, mutators=mutators, authenticate=user_id_from_jwt,
+    ))
+
+FastAPI is Starlette underneath: `app.router.routes.extend(zero_routes(...))`.
+"""
+
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+
+from zero_server.mutators import must_get_mutator
+from zero_server.protocol.mutation import CustomMutation, MutationResponse
+from zero_server.query.registry import must_get_query
+from zero_server.schema import Schema
+from zero_server.server.process_mutations import Database, TransactFn, handle_mutate_request
+from zero_server.server.process_queries import handle_query_request
+from zero_server.shared.json import JSONValue
+from zero_server.shared.registry import Registry
+
+type Authenticate = Callable[[Request], str | Awaitable[str | None] | None]
+"""The request's user ID, or `None` when logged out. Raise `Unauthorized` to answer 401."""
+type MakeContext = Callable[[Request, str | None], Any]
+"""The `ctx` queries and mutators receive. May be async."""
+
+
+class Unauthorized(Exception):
+    """Raised by `authenticate` for a token it rejects. The endpoint answers 401 instead of running."""
+
+
+async def _maybe_await(value: Any) -> Any:
+    return await value if inspect.isawaitable(value) else value
+
+
+def _default_context(_request: Request, user_id: str | None) -> dict[str, Any]:
+    return {"userID": user_id}
+
+
+def zero_routes(
+    *,
+    schema: Schema,
+    database: Database[Any] | None = None,
+    queries: Registry | None = None,
+    mutators: Registry | None = None,
+    authenticate: Authenticate,
+    context: MakeContext = _default_context,
+    query_path: str = "/query",
+    mutate_path: str = "/mutate",
+) -> list[Route]:
+    """Routes for whichever of the query and mutate endpoints you pass a registry for.
+
+    Queries resolve by name through `queries` and mutators through `mutators`, each called with the
+    `ctx` that `context` builds (by default `{"userID": user_id}`). Mutations run on `database`.
+    """
+    routes: list[Route] = []
+
+    async def caller(request: Request) -> tuple[str | None, Any] | Response:
+        try:
+            user_id = await _maybe_await(authenticate(request))
+        except Unauthorized as error:
+            return JSONResponse({"error": str(error) or "Unauthorized"}, status_code=401)
+        return user_id, await _maybe_await(context(request, user_id))
+
+    if queries is not None:
+
+        async def query(request: Request) -> Response:
+            who = await caller(request)
+            if isinstance(who, Response):
+                return who
+            user_id, ctx = who
+            response = await handle_query_request(
+                handler=lambda name, args: must_get_query(queries, name).fn(args=args, ctx=ctx),
+                schema=schema,
+                body=await request.body(),
+                user_id=user_id,
+            )
+            return JSONResponse(response.to_json())
+
+        routes.append(Route(query_path, query, methods=["POST"]))
+
+    if mutators is not None:
+        if database is None:
+            raise ValueError("the mutate endpoint needs a database")
+        db = database
+
+        async def mutate(request: Request) -> Response:
+            who = await caller(request)
+            if isinstance(who, Response):
+                return who
+            user_id, ctx = who
+
+            async def handler(transact: TransactFn[Any], _mutation: CustomMutation) -> MutationResponse:
+                async def run(tx: Any, name: str, args: JSONValue | None) -> None:
+                    await must_get_mutator(mutators, name).fn(tx=tx, ctx=ctx, args=args)
+
+                return await transact(run)
+
+            response = await handle_mutate_request(
+                db_provider=db,
+                handler=handler,
+                query=dict(request.query_params),
+                body=await request.body(),
+                user_id=user_id,
+            )
+            return JSONResponse(response.to_json())
+
+        routes.append(Route(mutate_path, mutate, methods=["POST"]))
+
+    return routes

zero_server/mutators.py

@@ -0,0 +1,87 @@
+"""`define_mutator` and `define_mutators`: named server mutators the mutate endpoint dispatches to.
+
+Ported from rocicorp/mono `packages/zql/src/mutate/mutator.ts` and `mutator-registry.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+
+A mutator here is the server half of the TypeScript mutator of the same name: the client runs its own
+optimistically, and this one runs authoritatively inside the mutation's transaction.
+"""
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, overload
+
+from zero_server.query.registry import is_schema_validator, validate_input
+from zero_server.shared.json import JSONValue
+from zero_server.shared.registry import Registry, build, merge, value_at_path
+
+type MutatorFn = Callable[..., Awaitable[None]]
+"""Called as `await fn(args=..., ctx=..., tx=...)`."""
+
+
+@dataclass(frozen=True)
+class MutatorDefinition:
+    fn: MutatorFn
+    validator: Any = None
+
+
+@overload
+def define_mutator(fn_or_validator: MutatorFn, fn: None = None) -> MutatorDefinition: ...
+@overload
+def define_mutator(fn_or_validator: Any, fn: MutatorFn) -> MutatorDefinition: ...
+@overload
+def define_mutator(fn_or_validator: Any, fn: None = None) -> Callable[[MutatorFn], MutatorDefinition]: ...
+def define_mutator(fn_or_validator: Any, fn: MutatorFn | None = None) -> Any:
+    """Define a mutator, called as `await fn(args=..., ctx=..., tx=...)`, in the three forms of
+    `define_query`: `define_mutator(fn)` or `@define_mutator`, `define_mutator(validator, fn)`, and
+    `@define_mutator(ArgsModel)`."""
+    if fn is not None:
+        return MutatorDefinition(fn=fn, validator=fn_or_validator)
+    if is_schema_validator(fn_or_validator):
+        return lambda decorated: MutatorDefinition(fn=decorated, validator=fn_or_validator)
+    return MutatorDefinition(fn=fn_or_validator)
+
+
+@dataclass(frozen=True)
+class MutateRequest:
+    mutator: "Mutator"
+    args: JSONValue | None
+
+
+class Mutator:
+    def __init__(self, name: str, definition: MutatorDefinition) -> None:
+        self.mutator_name = name
+        self._definition = definition
+
+    async def fn(self, *, args: JSONValue | None = None, ctx: Any = None, tx: Any) -> None:
+        validated = validate_input(self.mutator_name, args, self._definition.validator, "mutator")
+        await self._definition.fn(args=validated, ctx=ctx, tx=tx)
+
+    def __call__(self, args: JSONValue | None = None) -> MutateRequest:
+        return MutateRequest(mutator=self, args=args)
+
+
+type MutatorDefinitions = Mapping[str, "MutatorDefinition | MutatorDefinitions"]
+
+
+def define_mutators(
+    definitions: "MutatorDefinitions | Registry", overrides: "MutatorDefinitions | None" = None
+) -> Registry:
+    """Name each mutator by its dot-separated path through `definitions`, as `define_queries` does."""
+    is_definition = lambda value: isinstance(value, MutatorDefinition)  # noqa: E731
+    base = definitions if isinstance(definitions, Registry) else build(definitions, is_definition, Mutator)
+    if overrides is None:
+        return base
+    return merge(base, build(overrides, is_definition, Mutator))
+
+
+def get_mutator(mutators: Registry, name: str) -> Mutator | None:
+    found = value_at_path(mutators, name, ".")
+    return found if isinstance(found, Mutator) else None
+
+
+def must_get_mutator(mutators: Registry, name: str) -> Mutator:
+    mutator = get_mutator(mutators, name)
+    if mutator is None:
+        raise Exception(f"Mutator not found: {name}")
+    return mutator

zero_server/protocol/__init__.py

@@ -0,0 +1 @@
+"""Zero's wire types, from rocicorp/mono `packages/zero-protocol`."""

zero_server/protocol/application_error.py

@@ -0,0 +1,36 @@
+"""The error application code raises to send a message and JSON details back to the client.
+
+Ported from rocicorp/mono `packages/zero-protocol/src/application-error.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+"""
+
+from typing import Literal
+
+from zero_server.shared.error import get_error_details, get_error_message
+from zero_server.shared.json import JSONValue
+
+
+class ApplicationError(Exception):
+    def __init__(self, message: str, *, details: JSONValue | None = None, cause: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+        self.__cause__ = cause
+
+    @property
+    def kind(self) -> Literal["Application"]:
+        return "Application"
+
+
+def is_application_error(error: object) -> bool:
+    return isinstance(error, ApplicationError)
+
+
+def wrap_with_application_error(error: object) -> ApplicationError:
+    if isinstance(error, ApplicationError):
+        return error
+    return ApplicationError(
+        get_error_message(error),
+        cause=error if isinstance(error, BaseException) else None,
+        details=get_error_details(error),
+    )