Skip to content

Commit 576a443

Browse files
jnsdlsclaude
andauthored
feat: query endpoint, builder, registries and tx.mutate (#4)
handle_query_request ports process-queries.ts over a port of the ZQL builder (query-impl.ts, expression.ts), define_queries, and a schema loaded from JSON.stringify of the TypeScript schema, with the client to server name mapping. The wire tier interprets the same generated builder programs with the published createBuilder, defineQueries and handleQueryRequest and diffs the responses. A test schema with renamed tables and columns, compound keys, one- and two-hop relationships and a table without relationships puts every AST node type through it. Also ports tx.mutate's CRUD with upstream's text-cast conversions, the server schema check of ZQLDatabase, define_mutators and PushProcessor, each diffed against upstream through the mutate tier. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 498e460 commit 576a443

29 files changed

Lines changed: 2407 additions & 42 deletions

‎harness/mutate.ts‎

Lines changed: 87 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,20 @@
11
// The mutate half of the wire tier: the published handleMutateRequest over the postgres.js adapter,
22
// with mutators that tests/wire/mutators.py mirrors one for one.
3-
import {createSchema, string, table} from '@rocicorp/zero';
3+
import {
4+
boolean,
5+
createSchema,
6+
defineMutator,
7+
defineMutators,
8+
enumeration,
9+
json,
10+
number,
11+
string,
12+
table,
13+
} from '@rocicorp/zero';
414
import {
515
ApplicationError,
616
handleMutateRequest,
17+
PushProcessor,
718
type Database,
819
type MutateRequestHandler,
920
type TransactionProviderHooks,
@@ -13,10 +24,36 @@ import {zeroPostgresJS} from '@rocicorp/zero/server/adapters/postgresjs';
1324
import postgres from 'postgres';
1425

1526
const item = table('item').columns({id: string(), value: string()}).primaryKey('id');
16-
export const wireSchema = createSchema({tables: [item]});
27+
// One column per kind of conversion tx.mutate does on the way to Postgres.
28+
const thing = table('thing')
29+
.from('things')
30+
.columns({
31+
id: string(),
32+
n: number().optional(),
33+
f: number().optional(),
34+
b: boolean().optional(),
35+
j: json().optional(),
36+
t: number().from('happened_at').optional(),
37+
d: number().optional(),
38+
s: string().optional(),
39+
tags: json().optional(),
40+
u: string().optional(),
41+
mood: enumeration<'happy' | 'sad'>().optional(),
42+
tm: number().optional(),
43+
ttz: number().optional(),
44+
amount: number().optional(),
45+
ip: string().optional(),
46+
})
47+
.primaryKey('id');
48+
const pair = table('pair').columns({a: string(), b: number(), note: string().optional()}).primaryKey('a', 'b');
49+
export const wireSchema = createSchema({tables: [item, thing, pair]});
1750

18-
type Tx = {dbTransaction: {query(sql: string, params: unknown[]): Promise<unknown[]>}};
19-
type Args = {id?: string; value?: string; message?: string; details?: unknown};
51+
type Tx = {
52+
dbTransaction: {query(sql: string, params: unknown[]): Promise<unknown[]>};
53+
// oxlint-disable-next-line no-explicit-any
54+
mutate: any;
55+
};
56+
type Args = {id?: string; value?: string; message?: string; details?: unknown; table?: string; row?: unknown};
2057

2158
const PUT = `INSERT INTO item (id, value) VALUES ($1, $2)
2259
ON CONFLICT (id) DO UPDATE SET value = item.value || '+' || excluded.value`;
@@ -39,6 +76,10 @@ const mutators: Record<string, (tx: Tx, args: Args) => Promise<void>> = {
3976
await put(tx, args);
4077
throw new TypeError(String(args.message ?? 'bad type'));
4178
},
79+
'crud.insert': (tx, args) => tx.mutate[args.table!].insert(args.row),
80+
'crud.upsert': (tx, args) => tx.mutate[args.table!].upsert(args.row),
81+
'crud.update': (tx, args) => tx.mutate[args.table!].update(args.row),
82+
'crud.delete': (tx, args) => tx.mutate[args.table!].delete(args.row),
4283
'item.dbError': async tx => {
4384
await tx.dbTransaction.query('SELECT * FROM missing_table', []);
4485
},
@@ -96,3 +137,45 @@ export function mutate({
96137
}
97138

98139
export type {TransactionProviderHooks};
140+
141+
// PushProcessor dispatches by name to a registry from defineMutators, or to plain legacy functions.
142+
const registry = defineMutators({
143+
item: {
144+
put: defineMutator(async ({tx, args, ctx}: {tx: Tx; args: Args; ctx: {tag: string}}) =>
145+
put(tx, {...args, value: `${String(args?.value ?? '')}@${ctx.tag}`}),
146+
),
147+
appError: defineMutator(async ({tx, args}: {tx: Tx; args: Args}) => mutators['item.appError'](tx, args ?? {})),
148+
},
149+
} as never);
150+
const legacy = {legacy: {put: (tx: Tx, args: Args) => put(tx, args ?? {})}};
151+
152+
export function pushProcessor({url, query, body}: {url: string; query: Record<string, string>; body: unknown}) {
153+
return new PushProcessor(provider(url) as never, {tag: 'ctx'}, 'error').process(
154+
{...(registry as object), ...legacy} as never,
155+
query,
156+
body as never,
157+
);
158+
}
159+
160+
/** handleMutateRequest against `schema`, which may not match the database: its first transaction checks. */
161+
export function mutateWithSchema({
162+
url,
163+
schema,
164+
query,
165+
body,
166+
}: {
167+
url: string;
168+
schema: unknown;
169+
query: Record<string, string>;
170+
body: unknown;
171+
}) {
172+
const sql = postgres(url, {onnotice: () => {}});
173+
return handleMutateRequest({
174+
dbProvider: zeroPostgresJS(schema as never, sql) as never,
175+
handler,
176+
query,
177+
body: body as never,
178+
userID: null,
179+
logLevel: 'error',
180+
}).finally(() => sql.end());
181+
}

‎harness/ops.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ import {
99
transformRequestMessageSchema,
1010
v,
1111
} from './zero.ts';
12-
import {mutate} from './mutate.ts';
12+
import {mutate, mutateWithSchema, pushProcessor, wireSchema} from './mutate.ts';
13+
import {query, schemaJSON} from './query.ts';
1314

1415
// The schemas upstream parses requests with, and the mode it parses each in.
1516
const schemas = {
@@ -22,6 +23,11 @@ const schemas = {
2223

2324
export const ops = {
2425
mutate,
26+
pushProcessor,
27+
mutateWithSchema,
28+
query,
29+
schema: schemaJSON,
30+
wireSchema: () => JSON.parse(JSON.stringify(wireSchema)),
2531

2632
/** Whether upstream accepts `value` as a `schema`. */
2733
accepts({schema, value}: {schema: keyof typeof schemas; value: unknown}) {

‎harness/query.ts‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
// The query half of the wire tier: the published handleQueryRequest over queries that interpret a
2+
// builder program, which tests/wire/programs.py interprets the same way in Python.
3+
import {createBuilder, defineQueries, defineQuery, mustGetQuery} from '@rocicorp/zero';
4+
import {handleQueryRequest} from '@rocicorp/zero/server';
5+
import {QueryParseError} from './node_modules/@rocicorp/zero/out/zql/src/query/error.js';
6+
import {toStaticParam} from './node_modules/@rocicorp/zero/out/zero-protocol/src/ast.js';
7+
import {schema} from './schema.ts';
8+
9+
// oxlint-disable-next-line no-explicit-any
10+
type Q = any;
11+
type Sub = {ops: unknown[][]} | null;
12+
type Opts = {flip?: boolean; scalar?: boolean} | null;
13+
14+
const zql = createBuilder(schema) as Q;
15+
16+
function sub(program: Sub): ((q: Q) => Q) | undefined {
17+
return program ? q => apply(q, program.ops) : undefined;
18+
}
19+
20+
/** `{$param: [anchor, field]}` becomes a static parameter reference. */
21+
function v(value: unknown): unknown {
22+
if (typeof value === 'object' && value !== null && '$param' in value) {
23+
const [anchor, field] = (value as {$param: [string, string]}).$param;
24+
return {[toStaticParam]: () => ({type: 'static', anchor, field})};
25+
}
26+
return value;
27+
}
28+
29+
function expr(eb: Q, e: unknown[]): unknown {
30+
switch (e[0]) {
31+
case 'cmp':
32+
return e.length === 3 ? eb.cmp(e[1], v(e[2])) : eb.cmp(e[1], e[2], v(e[3]));
33+
case 'cmpLit':
34+
return eb.cmpLit(v(e[1]), e[2], v(e[3]));
35+
case 'and':
36+
return eb.and(...(e[1] as unknown[][]).map(x => expr(eb, x)));
37+
case 'or':
38+
return eb.or(...(e[1] as unknown[][]).map(x => expr(eb, x)));
39+
case 'not':
40+
return eb.not(expr(eb, e[1] as unknown[]));
41+
case 'exists':
42+
return eb.exists(e[1], sub(e[2] as Sub), (e[3] as Opts) ?? undefined);
43+
}
44+
throw new Error(`bad expression ${e[0]}`);
45+
}
46+
47+
function apply(q: Q, ops: unknown[][]): Q {
48+
for (const op of ops) {
49+
switch (op[0]) {
50+
case 'where':
51+
q = op.length === 3 ? q.where(op[1], v(op[2])) : q.where(op[1], op[2], v(op[3]));
52+
break;
53+
case 'whereFn':
54+
q = q.where((eb: Q) => expr(eb, op[1] as unknown[]));
55+
break;
56+
case 'whereExists': {
57+
const [, rel, program, opts] = op as [string, string, Sub, Opts];
58+
q = program ? q.whereExists(rel, sub(program), opts ?? undefined) : opts ? q.whereExists(rel, opts) : q.whereExists(rel);
59+
break;
60+
}
61+
case 'related':
62+
q = q.related(op[1], sub(op[2] as Sub));
63+
break;
64+
case 'orderBy':
65+
q = q.orderBy(op[1], op[2]);
66+
break;
67+
case 'limit':
68+
q = q.limit(op[1]);
69+
break;
70+
case 'start':
71+
q = op[2] === null ? q.start(op[1]) : q.start(op[1], {inclusive: op[2]});
72+
break;
73+
case 'one':
74+
q = q.one();
75+
break;
76+
default:
77+
throw new Error(`bad op ${op[0]}`);
78+
}
79+
}
80+
return q;
81+
}
82+
83+
type Program = {table: string; ops: unknown[][]};
84+
const run = ({args}: {args: Program}) => apply(zql[args.table], args.ops);
85+
86+
const program = {
87+
'~standard': {
88+
version: 1,
89+
vendor: 'zero-python',
90+
validate: (v: unknown) =>
91+
typeof v === 'object' && v !== null && typeof (v as Program).table === 'string'
92+
? {value: v}
93+
: {issues: [{message: 'expected a program'}]},
94+
},
95+
};
96+
97+
const queries = defineQueries({
98+
prog: defineQuery(run as never),
99+
nested: {prog: defineQuery(run as never)},
100+
validated: defineQuery(program as never, run as never),
101+
parseError: defineQuery(() => {
102+
throw new QueryParseError({cause: new Error('bad args')});
103+
}),
104+
appError: defineQuery(() => {
105+
throw new Error('nope');
106+
}),
107+
});
108+
109+
export function query({body, userID}: {body: unknown; userID: string | null}) {
110+
return handleQueryRequest({
111+
handler: (name, args) => mustGetQuery(queries, name).fn({args, ctx: undefined} as never),
112+
schema,
113+
body: body as never,
114+
query: {},
115+
userID,
116+
logLevel: 'error',
117+
});
118+
}
119+
120+
export function schemaJSON() {
121+
return JSON.parse(JSON.stringify(schema));
122+
}

‎harness/schema.ts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
// The wire tier's test schema. It has a table and columns renamed on the server, a compound primary
2+
// key, one-hop relationships of both cardinalities, a compound correlation, two-hop relationships
3+
// through a junction table, and a table with no relationships at all.
4+
import {boolean, createSchema, json, number, relationships, string, table} from '@rocicorp/zero';
5+
6+
const user = table('user')
7+
.from('users')
8+
.columns({id: string(), name: string().from('full_name'), age: number().optional(), active: boolean()})
9+
.primaryKey('id');
10+
const issue = table('issue')
11+
.columns({
12+
id: string(),
13+
ownerID: string().from('owner_id'),
14+
title: string(),
15+
meta: json().optional(),
16+
priority: number(),
17+
open: boolean(),
18+
})
19+
.primaryKey('id');
20+
const comment = table('comment')
21+
.columns({id: string(), issueID: string().from('issue_id'), authorID: string().from('author_id'), body: string()})
22+
.primaryKey('id');
23+
const label = table('label').columns({id: string(), name: string()}).primaryKey('id');
24+
const issueLabel = table('issueLabel')
25+
.from('issue_label')
26+
.columns({issueID: string().from('issue_id'), labelID: string().from('label_id')})
27+
.primaryKey('issueID', 'labelID');
28+
const audit = table('audit').columns({id: string(), at: number()}).primaryKey('id');
29+
30+
const userRelationships = relationships(user, ({many}) => ({
31+
issues: many({sourceField: ['id'], destField: ['ownerID'], destSchema: issue}),
32+
}));
33+
const issueRelationships = relationships(issue, ({one, many}) => ({
34+
owner: one({sourceField: ['ownerID'], destField: ['id'], destSchema: user}),
35+
comments: many({sourceField: ['id'], destField: ['issueID'], destSchema: comment}),
36+
ownComments: many({sourceField: ['id', 'ownerID'], destField: ['issueID', 'authorID'], destSchema: comment}),
37+
labels: many(
38+
{sourceField: ['id'], destField: ['issueID'], destSchema: issueLabel},
39+
{sourceField: ['labelID'], destField: ['id'], destSchema: label},
40+
),
41+
}));
42+
const commentRelationships = relationships(comment, ({one}) => ({
43+
issue: one({sourceField: ['issueID'], destField: ['id'], destSchema: issue}),
44+
author: one({sourceField: ['authorID'], destField: ['id'], destSchema: user}),
45+
}));
46+
const labelRelationships = relationships(label, ({many}) => ({
47+
issues: many(
48+
{sourceField: ['id'], destField: ['labelID'], destSchema: issueLabel},
49+
{sourceField: ['issueID'], destField: ['id'], destSchema: issue},
50+
),
51+
}));
52+
53+
export const schema = createSchema({
54+
tables: [user, issue, comment, label, issueLabel, audit],
55+
relationships: [userRelationships, issueRelationships, commentRelationships, labelRelationships],
56+
});

‎src/zero_python/__init__.py‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,36 @@
1-
"""Community Python server SDK for Rocicorp Zero. Not affiliated with Rocicorp."""
1+
"""Community Python server SDK for Rocicorp Zero. Not affiliated with Rocicorp.
2+
3+
The SQLAlchemy transaction provider lives in `zero_python.server.sqlalchemy` and needs the
4+
`zero-python[sqlalchemy]` extra.
5+
"""
6+
7+
from zero_python.mutators import define_mutator, define_mutators, get_mutator, must_get_mutator
8+
from zero_python.protocol.application_error import ApplicationError
9+
from zero_python.query.builder import Query, create_builder
10+
from zero_python.query.registry import QueryParseError, define_queries, define_query, get_query, must_get_query
11+
from zero_python.schema import Schema, load_schema
12+
from zero_python.server.process_mutations import handle_mutate_request
13+
from zero_python.server.process_queries import handle_query_request
14+
from zero_python.server.push_processor import PushProcessor
215

316
__version__ = "0.0.1"
17+
18+
__all__ = [
19+
"ApplicationError",
20+
"PushProcessor",
21+
"Query",
22+
"QueryParseError",
23+
"Schema",
24+
"create_builder",
25+
"define_mutator",
26+
"define_mutators",
27+
"define_queries",
28+
"define_query",
29+
"get_mutator",
30+
"get_query",
31+
"handle_mutate_request",
32+
"handle_query_request",
33+
"load_schema",
34+
"must_get_mutator",
35+
"must_get_query",
36+
]

0 commit comments

Comments
 (0)