Skip to content

Commit 9e95bb1

Browse files
jnsdlsclaude
andauthored
feat: support @rocicorp/zero 1.11.3 (#39)
## Summary Pins `@rocicorp/zero` **1.11.3** (from 1.10.0) and ports what changed in the server SDK between them. ```diff query builder - AST as built, normalized only when zero-cache hashes it + AST normalized at every step: related sorted by alias, where flattened + sorted + values ordered null < bool < number < string < array; static params comparable + empty and/or kept (always true / always false) z2s + LIKE patterns bound as text (non-string patterns match as their string) + char(n) compared as ::bpchar; bare `character` column named bpchar - $n::text::text -> $n::text mutate + mutator return value -> result.data, written to zero_0.mutations + tx.retry_on(predicate): re-run in a fresh tx, at most 5 runs per push + tx unusable once its transaction has ended + adapters take isolation_level= ZQLDatabase.run + bare statement when the connection supports it, no BEGIN/COMMIT query endpoint + transform requests parsed in strip mode (unknown fields ignored) compat proof + valita 0.5.5 (`dist/index.js`), scope remapped to 1.11.3 line numbers ``` Not ported: upstream's `LogSink` (Python logs through stdlib `logging`), and query interning, which only saves work. Upstream now interns built queries, and a few type-violating inputs share a key: a `flip` of `'yes'` with `true`, and any `orderBy` direction other than `'asc'` with `'desc'`. That made upstream's output depend on earlier programs. The harness now builds each program from a fresh schema, and `docs/compat.md` records it as a known difference. ## Evidence - **Before** (pin bumped, port unchanged): `pytest`: 53 failed, 661 passed (AST normalization, query bodies, SQL tier). **After:** `pytest`: 782 passed, `zero_server` at 100%; `python -m tests.compat`: 54 upstream modules and every port module fully exercised differentially. - New differential tests: - **Mutate:** return values, every `retry_on` outcome, using a `tx` after it ended, isolation level per adapter, `run` with and without a bare connection. - **SQL tier:** `char(3)` and `bpchar` columns, compared and matched with LIKE. - **Pinned builder programs:** each new sort rule. - **Not run locally:** e2e (port 55432 was held by an unrelated container). CI runs it. - **Wall-clock bench, Python side vs `main`:** | Case | `main` | This PR | Change | | --- | --- | --- | --- | | `build.simple` | 3.6 µs | 4.0 µs | about 13% slower | | `build.complex` | 20.1 µs | 23.3 µs | about 16% slower | | `query` cases | | | 7–16% slower | | `z2s` | | | unchanged | The cost is the per-step normalization upstream added. TS got faster at rebuilding the same query thanks to interning, so expect CodSpeed to flag `build`/`query`. Porting interning is the follow-up that wins this back. ## Merge Danger **Door:** two-way **Blast Radius:** wire Every query AST sent to zero-cache changes shape: key order, sorted conditions and relationships, and empty and/or now kept. This now matches what a 1.11.3 TypeScript server sends. A deployment still on zero-cache 1.10 would see different query hashes, which re-runs its queries. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- codesmith:footer --> --- <a href="https://app.blacksmith.sh/agent-labs-dev/codesmith/zero-python/pr/39?autoLogin=true&ref=codesmith_pr_footer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v3.svg"><source media="(prefers-color-scheme: light)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-light-v3.svg"><img alt="View with [code]smith" src="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v3-3x.png" width="162" height="28"></picture></a> <a href="https://backend.blacksmith.sh/track/enable-autofix?expires=1795812024&installation_model_id=434381&pr_number=39&ref=codesmith_pr_footer&repository=agent-labs-dev%2Fzero-python&return_to=https%3A%2F%2Fgithub.com%2Fagent-labs-dev%2Fzero-python%2Fpull%2F39&signature=1bb4b63b27217ea29779703a36fdaf667c13d82e31972f8fbc67b0adb8c81db9"><picture><source media="(prefers-color-scheme: dark)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-light.svg"><img alt="Autofix with [code]smith" src="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png" width="190" height="28"></picture></a> <sup>Need help on this PR? Tag <code>@codesmith-bot</code> with what you need.</sup> <!-- codesmith:autofix:disabled --> <!-- /codesmith:footer --> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent a6ad73e commit 9e95bb1

64 files changed

Lines changed: 1539 additions & 821 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ build/
99
.coverage
1010
node_modules/
1111
runner.log
12+
.coverage.*

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ A community Python server SDK for [Zero](https://zero.rocicorp.dev/). It is not
44

55
It ports what `@rocicorp/zero/server` gives a TypeScript backend: the query endpoint (`ZERO_QUERY_URL`), the mutate endpoint (`ZERO_MUTATE_URL`), the ZQL query builder, `defineQueries` and `defineMutators`, and `tx.mutate` and `tx.run` on Postgres. The client and `zero-cache` stay in TypeScript, and a Python backend serves the same TypeScript client a TypeScript backend would.
66

7-
Compatibility is pinned to one Zero release at a time. This version is tested against `@rocicorp/zero` **1.10.0** (see `ZERO_VERSION`).
7+
Compatibility is pinned to one Zero release at a time. This version is tested against `@rocicorp/zero` **1.11.3** (see `ZERO_VERSION`).
88

99
## Usage
1010

@@ -77,6 +77,9 @@ app = Starlette(
7777
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.
7878

7979
- **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.
80+
- **Mutator results.** What a mutator returns, if not `None`, reaches the client as the mutation's result data, and is also written to zero-cache's `mutations` table so it survives a lost response. Python has one `None`, so a mutator cannot return JSON `null` as data the way a TypeScript mutator can.
81+
- **Re-running a mutator.** `tx.retry_on(predicate)` asks `predicate(error, attempt)`, sync or async, whether to run the mutator again in a fresh transaction when the run fails, including at `COMMIT`. Only `True` means yes. A mutator runs at most 5 times per push, and `tx` is unusable once its transaction has ended, inside the predicate too.
82+
- **Isolation level.** Each adapter takes `isolation_level="read committed" | "repeatable read" | "serializable"` for the transactions mutations run in. Unset, the database's default applies.
8083
- **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.
8184
- **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.
8285

‎ZERO_VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.10.0
1+
1.11.3

‎bench/fixtures/query_server_schema_rows.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -518,5 +518,31 @@
518518
"typename": "timestamptz",
519519
"elemTyptype": null,
520520
"elemTypname": null
521+
},
522+
{
523+
"schema": "extra",
524+
"table": "gadgets",
525+
"column": "tag",
526+
"dataType": "character",
527+
"length": 3,
528+
"precision": null,
529+
"scale": null,
530+
"typtype": "b",
531+
"typename": "bpchar",
532+
"elemTyptype": null,
533+
"elemTypname": null
534+
},
535+
{
536+
"schema": "extra",
537+
"table": "gadgets",
538+
"column": "pad",
539+
"dataType": "character",
540+
"length": null,
541+
"precision": null,
542+
"scale": null,
543+
"typtype": "b",
544+
"typename": "bpchar",
545+
"elemTyptype": null,
546+
"elemTypname": null
521547
}
522548
]

‎bench/fixtures/schema.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,16 @@
269269
"type": "number",
270270
"optional": true,
271271
"customType": null
272+
},
273+
"tag": {
274+
"type": "string",
275+
"optional": true,
276+
"customType": null
277+
},
278+
"pad": {
279+
"type": "string",
280+
"optional": true,
281+
"customType": null
272282
}
273283
},
274284
"primaryKey": [

‎docs/compat.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,14 @@ These are the cases where the proof holds Python to something narrower than "ide
6767
- **Two failures in one query batch.** Upstream runs a batch's handlers together under `Promise.all`, and
6868
so does Python. When two of them fail the whole batch, which failure is reported depends on how each
6969
runtime orders its promise callbacks, and the two runtimes can disagree.
70+
- **Interned queries.** Upstream's builder hands back the query it built before when a step repeats one,
71+
keyed so that some values JavaScript's types rule out share a key: a `flip` of `'yes'` with `true`, any
72+
`orderBy` direction but `'asc'` with `'desc'`. In one process, such a value can come back as whichever
73+
was built first. Python builds what it is given. The harness gives each program a fresh schema, which
74+
upstream interns by, so that no comparison depends on the programs before it.
75+
- **A mutator returning `null`.** Upstream records a mutator's return value as result data unless it is
76+
`undefined`, so a TypeScript mutator can return `null` as data. Python has only `None`, which the port
77+
takes as returning nothing, as the tests' mutators never return `null`.
7078
- **The JavaScript object model.** Upstream's registries also resolve `~`, their marker key, and names every
7179
object inherits such as `toString`. A Python registry has neither.
7280
- **The runtime.** The oracle runs on Node 24, and JSON parse messages are V8's. Bun or Deno word them

‎e2e/docker-compose.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ services:
1515
retries: 60
1616

1717
zero-ts: &zero
18-
image: rocicorp/zero:1.10.0
18+
image: rocicorp/zero:1.11.3
1919
depends_on:
2020
postgres:
2121
condition: service_healthy

0 commit comments

Comments
 (0)