Zero
Preview. Zero on rowstile may change in any release, and is not part of what 1.0 will promise. Tell us what doesn't fit your app.
Zero syncs queries to clients: a client asks for a named query, zero-cache asks the app's server for its ZQL, runs it on its replica of the database, and keeps the client's copy current. zero-cache reads Postgres by logical replication, where row-level security doesn't run. So the policy's sync lines keep an index of who may read each row (the sync index), and the app's query endpoint adds the index's filter to each query, for whoever the request signs in as.
Everything here comes from integrations/zero, the conformance suite: a small Express app with Zero's two endpoints, zero-cache 1.11.4, and the checks on Zero's own client, in Node (integrations/zero/test.sh). The reference is Zero, in the sync index's page.
Install
# @next on each: the newest pre-release (until 0.1.0 a plain install gets it too)
npm install @rowstile/client@next @rowstile/pg@next @rocicorp/zero
npm install --save-dev rowstile@next # the commandThe policy
A sync line for each table Zero serves, and the role zero-cache connects as. A line with a permission syncs the rows whose readers hold it; one without, the rows the table's select rule gives.
app role conf_app
sync role conf_zero
sync app.files : view
sync app.folders
sync app.notesZero's role and its publication
zero-cache connects as a role of its own, which owns no table of the app's. Whoever runs the database makes it, as a superuser or the managed service's admin: a role that may make roles can give neither REPLICATION nor BYPASSRLS without holding them. zero-cache runs without event triggers (only a superuser may make them): a plain apply changes nothing it replicates, but a sync line added or dropped does, and zero-cache then resets, unless you call Zero's schema change hook.
# as an administrator, once
psql -c "CREATE ROLE conf_zero LOGIN PASSWORD '...' REPLICATION BYPASSRLS"The rest is the app's migrations. Zero reads each row by its primary key, so the tables keep their default replica identity, and Zero's role may read them, but for a column the policy masks:
-- Zero's role reads the synced tables, and of the notes every column but the body the policy masks
GRANT USAGE ON SCHEMA app TO conf_zero;
GRANT SELECT ON app.files, app.folders TO conf_zero;
GRANT SELECT (id, file_id, author_id) ON app.notes TO conf_zero;The publication comes after the policy's migration, since it names the index's tables: the synced tables, of the notes every column but the masked body, the keys each principal holds, and the readers of each synced table. Zero's role may create in the database, for its own schemas.
CREATE PUBLICATION zero_data FOR TABLE app.files, app.folders, app.notes (id, file_id, author_id), authz_sync.keys,
authz_sync.file__readers, authz_sync.folder__readers, authz_sync.note__readers;
DO $$ BEGIN EXECUTE format('GRANT CREATE ON DATABASE %I TO conf_zero', current_database()); END $$;zero-cache runs on its own role, the publication named, with the app's two endpoints, and Postgres with wal_level = logical. Once it has made its schemas, Zero's role lets the app role write Zero's record of each client's mutations, which the mutate endpoint keeps in each mutation's transaction:
docker run -e ZERO_UPSTREAM_DB="postgresql://conf_zero:...@db:5432/app" \
-e ZERO_CVR_DB="postgresql://conf_zero:...@db:5432/app" -e ZERO_CHANGE_DB="postgresql://conf_zero:...@db:5432/app" \
-e ZERO_APP_PUBLICATIONS=zero_data -e ZERO_QUERY_URL=https://app/api/zero/query \
-e ZERO_MUTATE_URL=https://app/api/zero/mutate -e ZERO_ADMIN_PASSWORD=... rocicorp/zero:1.11.4
psql -U conf_zero -c "GRANT USAGE ON SCHEMA zero_0 TO conf_app" \
-c "GRANT SELECT, INSERT, UPDATE ON zero_0.clients, zero_0.mutations TO conf_app"The index as Zero sees it: rowstile client zero
rowstile client zero writes a TypeScript module for the app's Zero schema: the index's tables as Zero tables and their relationships, the relationship each synced table needs to its readers, the columns the policy masks, and each table's filter. Under [clients] in rowstile.toml, rowstile client and rowstile dev write it with the other clients:
[clients]
ts = "src/authz.gen.ts"
zero = "src/zero.gen.ts"The app's Zero schema holds its own tables, never a masked column, each with its readers, and the index's:
import { readers, syncRelationships, syncTables } from "./zero.gen.js";
const note = table("note").from("app.notes")
.columns({ id: number(), file_id: number(), author_id: number() })
.primaryKey("id");
export const schema = createSchema({
tables: [file, folder, note, ...syncTables],
relationships: [
relationships(file, ({ many }) => ({ readers: many(readers["app.files"]) })),
relationships(folder, ({ many }) => ({ readers: many(readers["app.folders"]) })),
relationships(note, ({ many }) => ({ readers: many(readers["app.notes"]) })),
...syncRelationships,
],
});Each query adds its table's filter for whoever the context says, which the query endpoint makes:
export const queries = defineQueries({
files: defineQuery(({ ctx }) => readable["app.files"](zql.file, ctx).orderBy("id", "asc")),
folders: defineQuery(({ ctx }) => readable["app.folders"](zql.folder, ctx).orderBy("id", "asc")),
notes: defineQuery(({ ctx }) => readable["app.notes"](zql.note, ctx).orderBy("id", "asc")),
});The endpoints
zero-cache calls them with the client's token. Each asks the database who the request is, in the app's own way (here, a key signs in with authz.login_key(), else the token's user), with syncPrincipal from @rowstile/client:
export async function signedIn(token: Token): Promise<SyncPrincipal> {
if (token !== null && "key" in token) {
return sql.transaction(async (c) => {
await c.query("SELECT authz.login_key($1)", [token.key]);
return syncPrincipal(c);
});
}
return actingAs(token?.user ?? null, () => sql.transaction((c) => syncPrincipal(c)));
}A signed-out request is answered 401, and a session limited by scopes or viewing as someone 403, which Zero shows the client as needs-auth. Otherwise the query endpoint returns each query's ZQL, its context made from the request, never the client's:
const result = await handleQueryRequest({
handler: (name, args) => mustGetQuery(queries, name).fn({ args, ctx: asked.ctx }),
schema,
request: fetchRequest(req),
userID: asked.ctx.id,
});The mutate endpoint signs each mutation's transaction in as the request's user before the mutator runs, so the rules decide what it may write:
transact(async (tx, name, args) => {
// the transaction signed in first, as the request's key or user: what the mutator writes, the rules judge
if (token !== null && "key" in token) await tx.dbTransaction.query("SELECT authz.login_key($1)", [token.key]);
else {
const signIn = actAs({ type: ctx.type, id: ctx.id });
await tx.dbTransaction.query(signIn.text, signIn.values);
}
return mustGetMutator(mutators, name).fn({ args, tx, ctx });
}),Its server schema holds the app's own tables only: Zero checks a server schema's tables against those its connection holds a privilege on, and the app role holds none on the index.
export const writeSchema = createSchema({ tables: [file, folder, note] });Zero's own update doesn't count the rows it changed, and row-level security makes an update of a row the user may not update change none. On the server, write it as SQL and hand its result to the SDK's expect, which says whether the row was hidden or refused, and why; the client keeps Zero's own update, for its copy:
rename: defineMutator<{ id: number; name: string }>(async ({ tx, args }) => {
if (tx.location !== "server") return tx.mutate.file.update({ id: args.id, name: args.name });
const db = { query: async (text: string, values: unknown[]) => ({ rows: [...await tx.dbTransaction.query(text, values)] }) };
await calls(db).expect(await db.query("UPDATE app.files SET name = $1 WHERE id = $2 RETURNING id", [args.name, args.id]),
"app.files", "update", args.id);
}),What can't be done
- Rows already on a device stay there while it is offline, and in any copy the client keeps. A revoke stops delivery, and Zero removes the row when the client next syncs.
- The window after a change is zero-cache's replication lag, and for a share that ends, until the next
authz.sync_tick()too. - zero-cache asks the endpoints again when a client adds a query or connects again. Until then, a client signed in with a key revoked, or a session ended, since goes on getting its queries' changes.
- A client syncs the rows its queries read, the index's among them: its own keys and the readers rows they lead to, never another user's key.
- zero-cache is trusted: it holds BYPASSRLS and every row of what it publishes. rowstile can't check what it serves; the conformance suite checks it end to end.