zero-server 0.0.2__tar.gz → 0.0.3__tar.gz

{zero_server-0.0.2 → zero_server-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zero-server
-Version: 0.0.2
+Version: 0.0.3
 Summary: Community Python server SDK for Rocicorp Zero. Not affiliated with Rocicorp.
 Keywords: zero,rocicorp,sync,zql
 Author: Agent Labs
@@ -105,9 +105,9 @@ app = Starlette(
 )
 ```
 
-Point `ZERO_QUERY_URL` and `ZERO_MUTATE_URL` at `/query` and `/mutate`. With FastAPI, `app.router.routes.extend(zero_routes(...))`. With another framework, call `handle_query_request` and `handle_mutate_request` yourself; `zero_server/integrations/starlette.py` is short enough to copy.
+Point `ZERO_QUERY_URL` and `ZERO_MUTATE_URL` at `/query` and `/mutate`. With FastAPI, `app.router.routes.extend(zero_routes(...))`. With another framework, call `handle_query_request` and `handle_mutate_request` yourself; `zero_server/integrations/starlette.py` is short enough to copy. The types to annotate those handlers (`QueryRequestHandler`, `TransactFn`, `MutateResponse`, `MutationResponse`, `ServerPushFailed` and the rest) import from `zero_server`, and `server_ast(query, schema)` returns the AST zero-cache receives for a query.
 
-- **Databases.** `SQLAlchemyDatabase` (SQLAlchemy's asyncio engine on asyncpg or psycopg; the `sqlalchemy` extra installs neither driver), `AsyncpgDatabase` (an asyncpg pool) and `PsycopgDatabase` (a psycopg 3 async pool), under `zero_server.server.adapters`. Another driver plugs into `ZQLDatabase` as a `DBConnection` whose `query` takes `$1` placeholders.
+- **Databases.** `SQLAlchemyDatabase` (SQLAlchemy's asyncio engine on asyncpg or psycopg; the `sqlalchemy` extra installs neither driver), `AsyncpgDatabase` (an asyncpg pool) and `PsycopgDatabase` (a psycopg 3 async pool), under `zero_server.server.adapters`. A push's mutations run on one connection from the pool, taken at its first transaction and returned when the push ends. So mutators in one push share session state (a `SET` without `LOCAL`, session advisory locks, temp tables), and a handler that takes a second connection from the same pool while its push holds one can deadlock once the pool has fewer connections than there are concurrent pushes. Another driver plugs into `ZQLDatabase` as a `DBConnection` whose `query` takes `$1` placeholders.
 - **Validation.** `@define_query(Model)` and `@define_mutator(Model)` parse args with a Pydantic model or `TypeAdapter` first; a failure reaches the client as upstream's validation error.
 - **Strict building.** `create_builder(schema, strict=True)` refuses an unknown column when the query is built. Upstream only refuses it when the endpoint maps the query, failing the whole batch, so this is for your tests.
 
@@ -116,6 +116,7 @@ Point `ZERO_QUERY_URL` and `ZERO_MUTATE_URL` at `/query` and `/mutate`. With Fas
 The published npm package is the definition of correct. Every test diffs Python against it:
 
 - **Wire.** `harness/` runs the real `handleMutateRequest`, `handleQueryRequest`, `PushProcessor` and the query builder under Node. Hypothesis generates pushes (with duplicates, gaps, refusals and cleanup mutations) and builder programs, sends each through both sides against identical Postgres databases, and diffs the responses and every row written.
+- **HTTP.** The raw bytes of a request go to upstream's handlers as a Fetch `Request` and to the Starlette routes, so query-string parsing, body decoding and `JSON.parse`'s error messages are compared too, along with the response as `JSON.stringify` writes it.
 - **SQL.** The same generated queries run through upstream's `ZQLDatabase.run` and through `tx.run` against one seeded database, and the result rows are compared, never the SQL text.
 
 The wire and SQL tiers run against every adapter.
@@ -123,10 +124,15 @@ The wire and SQL tiers run against every adapter.
 
 Run them with `uv run pytest` (needs Node 24 and Docker, or `ZERO_SERVER_PG` pointing at a Postgres) and `uv run --group e2e python e2e/run.py`.
 
+A diff that passes only covers the inputs tried, so `uv run python -m tests.compat` then checks the inputs were enough. Every line and branch of the upstream modules the port cites must have run inside the npm package during the tests, and every line and branch of `zero_server` must have run during a differential test. [`docs/compat.md`](docs/compat.md) explains the check, lists what it leaves out and why, and records the known differences.
+
+## Performance
+
+`bench/` runs the same workloads through zero-server and the published package. The CPU-only cases (the query endpoint, request parsing, the mutate endpoint over an in-memory database, z2s) are [CodSpeed](https://codspeed.io) benchmarks on both sides, and CodSpeed flags a pull request that makes any of them slower. `uv run python -m bench` times every case on the wall clock, including those that wait on Postgres (`tx.run`, mutate, `PushProcessor`, per adapter), and prints each case's Python/TypeScript ratio. CI shows that table without gating on it. `bench/__init__.py` has the commands.
+
 ## Known differences
 
-- **Parse errors.** When a request is malformed, the message after `Failed to parse push body:` describes the bad field in Pydantic's words, not valita's. The rest of the response matches, and zero-cache only logs it.
-- **Non-string values against text columns.** Upstream passes such a value to the JavaScript driver as is, so the driver decides how it binds. zero-server binds `String(value)`, which is what postgres.js does except for an array whose first element is a boolean, which it binds as `false`.
+[`docs/compat.md`](docs/compat.md#known-differences) has the full list. The two most likely to matter: the deprecated upstream exports (`handleTransformRequest`, `getMutation`, the positional handler overloads, `tx.query` and the rest) are not ported, and where upstream's result depends on its JavaScript driver, zero-server does what the postgres.js adapter does.
 
 ## License
 

{zero_server-0.0.2 → zero_server-0.0.3}/README.md

@@ -74,9 +74,9 @@ app = Starlette(
 )
 ```
 
-Point `ZERO_QUERY_URL` and `ZERO_MUTATE_URL` at `/query` and `/mutate`. With FastAPI, `app.router.routes.extend(zero_routes(...))`. With another framework, call `handle_query_request` and `handle_mutate_request` yourself; `zero_server/integrations/starlette.py` is short enough to copy.
+Point `ZERO_QUERY_URL` and `ZERO_MUTATE_URL` at `/query` and `/mutate`. With FastAPI, `app.router.routes.extend(zero_routes(...))`. With another framework, call `handle_query_request` and `handle_mutate_request` yourself; `zero_server/integrations/starlette.py` is short enough to copy. The types to annotate those handlers (`QueryRequestHandler`, `TransactFn`, `MutateResponse`, `MutationResponse`, `ServerPushFailed` and the rest) import from `zero_server`, and `server_ast(query, schema)` returns the AST zero-cache receives for a query.
 
-- **Databases.** `SQLAlchemyDatabase` (SQLAlchemy's asyncio engine on asyncpg or psycopg; the `sqlalchemy` extra installs neither driver), `AsyncpgDatabase` (an asyncpg pool) and `PsycopgDatabase` (a psycopg 3 async pool), under `zero_server.server.adapters`. Another driver plugs into `ZQLDatabase` as a `DBConnection` whose `query` takes `$1` placeholders.
+- **Databases.** `SQLAlchemyDatabase` (SQLAlchemy's asyncio engine on asyncpg or psycopg; the `sqlalchemy` extra installs neither driver), `AsyncpgDatabase` (an asyncpg pool) and `PsycopgDatabase` (a psycopg 3 async pool), under `zero_server.server.adapters`. A push's mutations run on one connection from the pool, taken at its first transaction and returned when the push ends. So mutators in one push share session state (a `SET` without `LOCAL`, session advisory locks, temp tables), and a handler that takes a second connection from the same pool while its push holds one can deadlock once the pool has fewer connections than there are concurrent pushes. Another driver plugs into `ZQLDatabase` as a `DBConnection` whose `query` takes `$1` placeholders.
 - **Validation.** `@define_query(Model)` and `@define_mutator(Model)` parse args with a Pydantic model or `TypeAdapter` first; a failure reaches the client as upstream's validation error.
 - **Strict building.** `create_builder(schema, strict=True)` refuses an unknown column when the query is built. Upstream only refuses it when the endpoint maps the query, failing the whole batch, so this is for your tests.
 
@@ -85,6 +85,7 @@ Point `ZERO_QUERY_URL` and `ZERO_MUTATE_URL` at `/query` and `/mutate`. With Fas
 The published npm package is the definition of correct. Every test diffs Python against it:
 
 - **Wire.** `harness/` runs the real `handleMutateRequest`, `handleQueryRequest`, `PushProcessor` and the query builder under Node. Hypothesis generates pushes (with duplicates, gaps, refusals and cleanup mutations) and builder programs, sends each through both sides against identical Postgres databases, and diffs the responses and every row written.
+- **HTTP.** The raw bytes of a request go to upstream's handlers as a Fetch `Request` and to the Starlette routes, so query-string parsing, body decoding and `JSON.parse`'s error messages are compared too, along with the response as `JSON.stringify` writes it.
 - **SQL.** The same generated queries run through upstream's `ZQLDatabase.run` and through `tx.run` against one seeded database, and the result rows are compared, never the SQL text.
 
 The wire and SQL tiers run against every adapter.
@@ -92,10 +93,15 @@ The wire and SQL tiers run against every adapter.
 
 Run them with `uv run pytest` (needs Node 24 and Docker, or `ZERO_SERVER_PG` pointing at a Postgres) and `uv run --group e2e python e2e/run.py`.
 
+A diff that passes only covers the inputs tried, so `uv run python -m tests.compat` then checks the inputs were enough. Every line and branch of the upstream modules the port cites must have run inside the npm package during the tests, and every line and branch of `zero_server` must have run during a differential test. [`docs/compat.md`](docs/compat.md) explains the check, lists what it leaves out and why, and records the known differences.
+
+## Performance
+
+`bench/` runs the same workloads through zero-server and the published package. The CPU-only cases (the query endpoint, request parsing, the mutate endpoint over an in-memory database, z2s) are [CodSpeed](https://codspeed.io) benchmarks on both sides, and CodSpeed flags a pull request that makes any of them slower. `uv run python -m bench` times every case on the wall clock, including those that wait on Postgres (`tx.run`, mutate, `PushProcessor`, per adapter), and prints each case's Python/TypeScript ratio. CI shows that table without gating on it. `bench/__init__.py` has the commands.
+
 ## Known differences
 
-- **Parse errors.** When a request is malformed, the message after `Failed to parse push body:` describes the bad field in Pydantic's words, not valita's. The rest of the response matches, and zero-cache only logs it.
-- **Non-string values against text columns.** Upstream passes such a value to the JavaScript driver as is, so the driver decides how it binds. zero-server binds `String(value)`, which is what postgres.js does except for an array whose first element is a boolean, which it binds as `false`.
+[`docs/compat.md`](docs/compat.md#known-differences) has the full list. The two most likely to matter: the deprecated upstream exports (`handleTransformRequest`, `getMutation`, the positional handler overloads, `tx.query` and the rest) are not ported, and where upstream's result depends on its JavaScript driver, zero-server does what the postgres.js adapter does.
 
 ## License
 

{zero_server-0.0.2 → zero_server-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zero-server"
-version = "0.0.2"
+version = "0.0.3"
 description = "Community Python server SDK for Rocicorp Zero. Not affiliated with Rocicorp."
 readme = "README.md"
 license = "Apache-2.0"
@@ -56,6 +56,7 @@ dev = [
     "pytest-cov>=7.1",
     "ruff>=0.17",
     "ty>=0.0.87",
+    "pytest-codspeed>=5.0.3",
 ]
 e2e = [
     "starlette>=1.6",
@@ -89,7 +90,7 @@ testpaths = ["tests"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"
 asyncio_default_test_loop_scope = "session"
-addopts = "--cov=zero_server --cov-branch --cov-report=term-missing"
+addopts = "--cov=zero_server --cov-branch --cov-context=test --cov-report=term-missing"
 
 [tool.coverage.run]
 concurrency = [

{zero_server-0.0.2 → zero_server-0.0.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "zero-server"
-version = "0.0.2"
+version = "0.0.3"
 description = "Community Python server SDK for Rocicorp Zero. Not affiliated with Rocicorp."
 readme = "README.md"
 license = "Apache-2.0"
@@ -46,6 +46,7 @@ dev = [
     "pytest-cov>=7.1",
     "ruff>=0.17",
     "ty>=0.0.87",
+    "pytest-codspeed>=5.0.3",
 ]
 
 # The Python app server of the end-to-end tier.
@@ -67,7 +68,7 @@ testpaths = ["tests"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"
 asyncio_default_test_loop_scope = "session"
-addopts = "--cov=zero_server --cov-branch --cov-report=term-missing"
+addopts = "--cov=zero_server --cov-branch --cov-context=test --cov-report=term-missing"
 
 [tool.coverage.run]
 # SQLAlchemy's asyncio layer resumes coroutines inside greenlets.

zero_server-0.0.3/src/zero_server/__init__.py

@@ -0,0 +1,73 @@
+"""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.protocol.ast import AST
+from zero_server.protocol.error import ErrorReason, ServerPushFailed
+from zero_server.protocol.mutate_server import MutateSuccess
+from zero_server.protocol.mutation import (
+    CustomMutation,
+    MutationAppError,
+    MutationOk,
+    MutationResponse,
+    MutationZeroError,
+)
+from zero_server.protocol.push import PushBody
+from zero_server.query.builder import Builder, OneQuery, Query, create_builder
+from zero_server.query.expression import ExpressionBuilder
+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 (
+    MutateResponse,
+    OutOfOrderMutation,
+    TransactFn,
+    handle_mutate_request,
+)
+from zero_server.server.process_queries import QueryRequestHandler, handle_query_request, server_ast
+from zero_server.server.push_processor import PushProcessor
+from zero_server.shared.json import JSONValue
+
+__version__ = "0.0.3"
+
+__all__ = [
+    "AST",
+    "ApplicationError",
+    "Builder",
+    "CustomMutation",
+    "ErrorReason",
+    "ExpressionBuilder",
+    "JSONValue",
+    "MutateResponse",
+    "MutateSuccess",
+    "MutationAppError",
+    "MutationOk",
+    "MutationResponse",
+    "MutationZeroError",
+    "OneQuery",
+    "OutOfOrderMutation",
+    "PushBody",
+    "PushProcessor",
+    "Query",
+    "QueryParseError",
+    "QueryRequestHandler",
+    "Schema",
+    "ServerPushFailed",
+    "TransactFn",
+    "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",
+    "server_ast",
+]

{zero_server-0.0.2 → zero_server-0.0.3}/src/zero_server/integrations/starlette.py

@@ -21,6 +21,7 @@ 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.js import js_stringify
 from zero_server.shared.json import JSONValue
 from zero_server.shared.registry import Registry
 
@@ -30,6 +31,13 @@ type MakeContext = Callable[[Request, str | None], Any]
 """The `ctx` queries and mutators receive. May be async."""
 
 
+class _JSONResponse(JSONResponse):
+    """The bytes a TypeScript server sends: `JSON.stringify`'s text, which escapes any lone surrogate."""
+
+    def render(self, content: Any) -> bytes:
+        return js_stringify(content).encode()
+
+
 class Unauthorized(Exception):
     """Raised by `authenticate` for a token it rejects. The endpoint answers 401 instead of running."""
 
@@ -63,15 +71,15 @@ def zero_routes(
     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)
+        except Unauthorized as error:  # python-only: upstream leaves authentication to the app's route
+            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):
+            if isinstance(who, Response):  # python-only: the 401 from `authenticate`
                 return who
             user_id, ctx = who
             response = await handle_query_request(
@@ -80,18 +88,18 @@ def zero_routes(
                 body=await request.body(),
                 user_id=user_id,
             )
-            return JSONResponse(response.to_json())
+            return _JSONResponse(response.to_json())
 
         routes.append(Route(query_path, query, methods=["POST"]))
 
     if mutators is not None:
-        if database is None:
+        if database is None:  # python-only: a configuration error in these routes' own arguments
             raise ValueError("the mutate endpoint needs a database")
         db = database
 
         async def mutate(request: Request) -> Response:
             who = await caller(request)
-            if isinstance(who, Response):
+            if isinstance(who, Response):  # python-only: the 401 from `authenticate`
                 return who
             user_id, ctx = who
 
@@ -108,7 +116,7 @@ def zero_routes(
                 body=await request.body(),
                 user_id=user_id,
             )
-            return JSONResponse(response.to_json())
+            return _JSONResponse(response.to_json())
 
         routes.append(Route(mutate_path, mutate, methods=["POST"]))
 

{zero_server-0.0.2 → zero_server-0.0.3}/src/zero_server/mutators.py

@@ -37,7 +37,7 @@ def define_mutator(fn_or_validator: Any, fn: MutatorFn | None = None) -> Any:
     `@define_mutator(ArgsModel)`."""
     if fn is not None:
         return MutatorDefinition(fn=fn, validator=fn_or_validator)
-    if is_schema_validator(fn_or_validator):
+    if is_schema_validator(fn_or_validator):  # python-only: the decorator form, `@define_mutator(Model)`
         return lambda decorated: MutatorDefinition(fn=decorated, validator=fn_or_validator)
     return MutatorDefinition(fn=fn_or_validator)
 
@@ -75,12 +75,12 @@ def define_mutators(
     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 get_mutator(mutators: Registry, name: str) -> Mutator | Registry | None:
+    """The mutator at a dot-separated `name`, or, as upstream has it, the namespace there."""
+    return value_at_path(mutators, name, ".")
 
 
-def must_get_mutator(mutators: Registry, name: str) -> Mutator:
+def must_get_mutator(mutators: Registry, name: str) -> Mutator | Registry:
     mutator = get_mutator(mutators, name)
     if mutator is None:
         raise Exception(f"Mutator not found: {name}")

{zero_server-0.0.2 → zero_server-0.0.3}/src/zero_server/protocol/application_error.py

@@ -11,6 +11,9 @@ from zero_server.shared.json import JSONValue
 
 
 class ApplicationError(Exception):
+    # Upstream's constructor sets the name, so a subclass reports it too.
+    error_name = "ApplicationError"
+
     def __init__(self, message: str, *, details: JSONValue | None = None, cause: BaseException | None = None) -> None:
         super().__init__(message)
         self.message = message
@@ -26,11 +29,7 @@ def is_application_error(error: object) -> bool:
     return isinstance(error, ApplicationError)
 
 
-def wrap_with_application_error(error: object) -> ApplicationError:
+def wrap_with_application_error(error: BaseException) -> 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),
-    )
+    return ApplicationError(get_error_message(error), cause=error, details=get_error_details(error))