rizolang 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +43 -12
- package/build/src/ast.d.ts +17 -2
- package/build/src/ast.js.map +1 -1
- package/build/src/check-api.d.ts +7 -0
- package/build/src/check-api.js +66 -8
- package/build/src/check-api.js.map +1 -1
- package/build/src/cli.d.ts +1 -0
- package/build/src/cli.js +81 -5
- package/build/src/cli.js.map +1 -1
- package/build/src/compiler.d.ts +2 -0
- package/build/src/compiler.js +2 -1
- package/build/src/compiler.js.map +1 -1
- package/build/src/emit/routes.d.ts +2 -0
- package/build/src/emit/routes.js +78 -8
- package/build/src/emit/routes.js.map +1 -1
- package/build/src/emit/sql.d.ts +3 -4
- package/build/src/emit/sql.js +13 -70
- package/build/src/emit/sql.js.map +1 -1
- package/build/src/emit/typescript.js +4 -1
- package/build/src/emit/typescript.js.map +1 -1
- package/build/src/migrations.d.ts +33 -0
- package/build/src/migrations.js +183 -0
- package/build/src/migrations.js.map +1 -0
- package/build/src/parser.js +40 -5
- package/build/src/parser.js.map +1 -1
- package/build/src/schema.d.ts +63 -0
- package/build/src/schema.js +151 -0
- package/build/src/schema.js.map +1 -0
- package/build/src/version.d.ts +1 -1
- package/build/src/version.js +1 -1
- package/docs/SPEC-COMPACT.md +13 -4
- package/docs/SPEC.md +105 -17
- package/package.json +4 -1
- package/runtime/migrate.ts +131 -0
- package/runtime/server.ts +264 -17
- package/runtime/session.ts +2 -0
- package/runtime/types.ts +36 -1
package/docs/SPEC-COMPACT.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Rizo Lang (compact spec, v0.
|
|
1
|
+
# Rizo Lang (compact spec, v0.3)
|
|
2
2
|
|
|
3
3
|
You are writing Rizo Lang (`.rz` files). Follow these rules exactly. A file contains only `model` blocks, at most one `auth` line, and `api` blocks. Never write SQL, TypeScript or `page` blocks in `.rz` files.
|
|
4
4
|
|
|
@@ -76,19 +76,23 @@ A field named `password` (or ending in `Password`) must have the type `Password`
|
|
|
76
76
|
|
|
77
77
|
## auth
|
|
78
78
|
|
|
79
|
-
`auth User by email` turns on accounts. User needs `email: Email unique` and one `Password` field. It adds `POST /auth/signup`, `POST /auth/login`, `POST /auth/logout`
|
|
79
|
+
`auth User by email` turns on accounts. User needs `email: Email unique` and one `Password` field. It adds `POST /auth/signup`, `POST /auth/login`, `POST /auth/logout`, `POST /auth/logout-all`, `GET /auth/me`, `PATCH /auth/me` (edit profile), `POST /auth/password` and `DELETE /auth/me`. Sessions use a secure cookie. Don't write your own login endpoints.
|
|
80
|
+
|
|
81
|
+
Roles: `auth User by email roles admin, editor` (must include admin). Admins assign roles with `PUT /auth/users/:id/role`. Never add a `role` field yourself; it is hidden and never comes from request bodies.
|
|
80
82
|
|
|
81
83
|
## api
|
|
82
84
|
|
|
83
85
|
```
|
|
84
86
|
api METHOD /path/:param -> Model.public {
|
|
85
87
|
public (or: requires login)
|
|
86
|
-
requires
|
|
88
|
+
requires role admin, editor (optional; needs requires login)
|
|
89
|
+
requires owner <link field> (optional; add "or role admin" to let admins act too)
|
|
87
90
|
return db.Model.action(arguments)
|
|
88
91
|
}
|
|
89
92
|
```
|
|
90
93
|
|
|
91
94
|
- Every endpoint has **exactly one** of `public` or `requires login`.
|
|
95
|
+
- `requires role admin` gives 403 to users without that role.
|
|
92
96
|
- `requires owner author` lets only the record's owner act; others get 404. It needs `requires login`, and it works with find, update and delete. It is **required** on update and delete of a model that links to the auth model.
|
|
93
97
|
- The return type is `-> Model.public` or `-> list Model.public`, and there is none for delete. Only `.public` can be returned.
|
|
94
98
|
- Paths use lowercase segments and `:camelCase` parameters. Every parameter must be used. `/auth` is reserved.
|
|
@@ -96,16 +100,21 @@ api METHOD /path/:param -> Model.public {
|
|
|
96
100
|
| Action | Method | Result |
|
|
97
101
|
|---------------------------------|--------------|--------------------|
|
|
98
102
|
| `db.M.find(id)` | GET | one record or 404 |
|
|
99
|
-
| `db.M.list(filters, order f desc, limit N)` | GET |
|
|
103
|
+
| `db.M.list(filters, order f desc, limit N)` | GET | `{ items, next }` page (limit ≤ 100, default 50) |
|
|
100
104
|
| `db.M.create(body)` | POST | 201 new record |
|
|
101
105
|
| `db.M.update(id, body)` | PUT or PATCH | changed record or 404 |
|
|
102
106
|
| `db.M.delete(id)` | DELETE | 204 or 404 |
|
|
103
107
|
|
|
104
108
|
- Filters are `field = value`. A value is `me`, a path parameter, a number, `true` or `false`.
|
|
105
109
|
- `body` is the validated JSON request body.
|
|
110
|
+
- `list` returns pages: clients call `?limit=10`, then `?after=<next>`. You can't order by an optional field.
|
|
106
111
|
- A link to the auth model must be set with `= me` in create, and is never taken from body.
|
|
107
112
|
- You cannot create, update or delete the auth model through `api`.
|
|
108
113
|
|
|
114
|
+
## Migrations
|
|
115
|
+
|
|
116
|
+
`rizolang build` writes `migrations/NNNN_*.sql` when models change. Removing a model or field, changing a field's type, or removing a role is refused (RZ0904). Never rename a field; add a new one instead. Apply migrations with `node migrate.ts`.
|
|
117
|
+
|
|
109
118
|
## Errors
|
|
110
119
|
|
|
111
120
|
The format is `file.rz:LINE:COL error RZxxxx: message`, followed by a `fix:` line. Apply the fix exactly as written.
|
package/docs/SPEC.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Rizo Lang Specification
|
|
2
2
|
|
|
3
|
-
Version 0.
|
|
3
|
+
Version 0.3 (draft) · Milestone 3: roles, pagination, accounts and migrations
|
|
4
4
|
|
|
5
5
|
Rizo Lang is a secure, simple, full-stack web language. Source files end in `.rz`. The compiler, `rizolang`, turns Rizo Lang into existing technology: a PostgreSQL schema, TypeScript types and a Node.js server. HTML and TypeScript frontends come later.
|
|
6
6
|
|
|
@@ -133,15 +133,16 @@ Modifiers come after the type, on the same line, in any order, each at most once
|
|
|
133
133
|
auth User by email
|
|
134
134
|
```
|
|
135
135
|
|
|
136
|
-
This line turns on accounts and sessions. It is written `auth <Model> by <field
|
|
136
|
+
This line turns on accounts and sessions. It is written `auth <Model> by <field>`, optionally followed by `roles <name>, <name>, ...`.
|
|
137
137
|
|
|
138
138
|
Rules (error RZ0317):
|
|
139
139
|
- The field must be declared as `Email unique`, and it must not be optional.
|
|
140
140
|
- The model must have exactly one required `Password` field.
|
|
141
141
|
- A link from the model to itself must be optional.
|
|
142
142
|
- There can be at most one `auth` line per file.
|
|
143
|
+
- Roles, if declared, are camelCase names, at most 20 of them, and must include `admin`. The model must not have its own field named `role`.
|
|
143
144
|
|
|
144
|
-
It adds
|
|
145
|
+
It adds these endpoints. Paths under `/auth` are reserved.
|
|
145
146
|
|
|
146
147
|
| Endpoint | Body | Result |
|
|
147
148
|
|---------------------|-----------------------------------|-----------------------------------------------|
|
|
@@ -149,12 +150,41 @@ It adds four endpoints. Paths under `/auth` are reserved.
|
|
|
149
150
|
| `POST /auth/login` | `{ "email": ..., "password": ... }` | 200 with `User.public`, or 401 |
|
|
150
151
|
| `POST /auth/logout` | none | 204; the session is deleted |
|
|
151
152
|
| `GET /auth/me` | none | 200 with `User.public`, or 401 |
|
|
153
|
+
| `PATCH /auth/me` | Any profile fields | 200 with `User.public`. Every field is optional. The login email, the password, the role and links to the auth model can't be changed here |
|
|
154
|
+
| `POST /auth/password` | `{ "currentPassword": ..., "newPassword": ... }` | 204. Every other session of the account is logged out |
|
|
155
|
+
| `POST /auth/logout-all` | none | 204. Every session of the account is deleted, including this one |
|
|
156
|
+
| `DELETE /auth/me` | `{ "password": ... }` | 204, and the account and its sessions are deleted. 409 if other records still link to it |
|
|
152
157
|
|
|
153
158
|
**How login works**
|
|
154
159
|
- Passwords are hashed with scrypt (N=2^15, r=8, p=3) and a random salt.
|
|
155
160
|
- A wrong password and an unknown email give the same 401 response, in about the same time.
|
|
156
161
|
- After 5 failed logins for an account, or 20 from one address, within 15 minutes, login answers 429. Signups are limited to 10 per hour per address.
|
|
157
162
|
|
|
163
|
+
### 4.1 Roles
|
|
164
|
+
|
|
165
|
+
```rizo
|
|
166
|
+
auth User by email roles admin, editor
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Each account has at most one role, or none.
|
|
170
|
+
- **Storage:** the role is kept in a hidden `role` column that only accepts the declared names.
|
|
171
|
+
- **Never from or to clients:** the role is never accepted in a request body and never appears in any response or public type.
|
|
172
|
+
- **Checked on every request:** a role change applies to existing sessions immediately.
|
|
173
|
+
|
|
174
|
+
**Assigning roles.** Admins use a built-in endpoint:
|
|
175
|
+
|
|
176
|
+
| Endpoint | Body | Result |
|
|
177
|
+
|----------|------|--------|
|
|
178
|
+
| `PUT /auth/users/:id/role` | `{ "role": "editor" }` or `{ "role": null }` | 200 `{ "id", "role" }`. Admins only: 401 if not logged in, 403 if not an admin or if it's your own account |
|
|
179
|
+
|
|
180
|
+
**The first admin.** Sign up normally, then start the server with `RIZO_ADMIN_EMAILS=you@example.com`. At startup, accounts that **already exist** with a listed email become admins. Accounts created later are never promoted this way, so nobody can claim admin by signing up with a listed email.
|
|
181
|
+
|
|
182
|
+
**Sensitive changes:**
|
|
183
|
+
- Changing the password and deleting the account need the current password.
|
|
184
|
+
- A wrong password gets 403 and counts toward the same lockout as login.
|
|
185
|
+
- New passwords follow the Password field's `min` and `max`.
|
|
186
|
+
- Changing the login email isn't available yet, because it needs email verification.
|
|
187
|
+
|
|
158
188
|
**How sessions work**
|
|
159
189
|
- The session is a random 256-bit token in the `rizo_session` cookie: `HttpOnly; Secure; SameSite=Lax; Path=/`, lasting 7 days.
|
|
160
190
|
- The database stores only a SHA-256 hash of the token, in the table `_rizo_sessions`.
|
|
@@ -175,7 +205,8 @@ An endpoint has a header, an access rule, an optional owner rule and one return
|
|
|
175
205
|
```
|
|
176
206
|
api <METHOD> <path> [-> <return type>] {
|
|
177
207
|
public | requires login
|
|
178
|
-
[requires
|
|
208
|
+
[requires role <role>, <role>]
|
|
209
|
+
[requires owner <link field> [or role <role>, <role>]]
|
|
179
210
|
return db.<Model>.<action>(<arguments>)
|
|
180
211
|
}
|
|
181
212
|
```
|
|
@@ -208,7 +239,12 @@ There is no default, so an endpoint can never be left open by accident. `require
|
|
|
208
239
|
- `<field>` must be a link to the auth model, for example `author`.
|
|
209
240
|
- It works with `find`, `update` and `delete`.
|
|
210
241
|
- The check is part of the SQL `WHERE` clause. A record owned by someone else behaves exactly like a missing one (404), so callers can't tell that it exists.
|
|
211
|
-
- It is **required** for `update` and `delete` on a model that links to the auth model (RZ0331),
|
|
242
|
+
- It is **required** for `update` and `delete` on a model that links to the auth model (RZ0331), unless the endpoint has `requires role`. That way one user can never change another user's records.
|
|
243
|
+
- `requires owner author or role admin` also lets the listed roles act on records they don't own. This check is part of the `WHERE` clause too.
|
|
244
|
+
|
|
245
|
+
`requires role admin, editor` only lets users with one of the listed roles call the endpoint; anyone else gets 403.
|
|
246
|
+
- It needs `requires login`, and the roles must be declared on the `auth` line (RZ0332).
|
|
247
|
+
- With `update` or `delete`, it lets those roles change any record.
|
|
212
248
|
- A public endpoint can't update or delete such a model either: `requires owner` needs `requires login`.
|
|
213
249
|
|
|
214
250
|
### 5.3 Queries
|
|
@@ -218,15 +254,15 @@ The return line is `return db.<Model>.<action>(...)`. There are five actions. Ea
|
|
|
218
254
|
| Action | Method | Arguments | Result |
|
|
219
255
|
|----------|---------------|---------------------------------------------------|-------------------------------------------|
|
|
220
256
|
| `find` | GET | `(id)`: a path parameter | 200 with the record, or 404 |
|
|
221
|
-
| `list` | GET | filters, `order`, `limit` (all optional) | 200 with
|
|
257
|
+
| `list` | GET | filters, `order`, `limit` (all optional) | 200 with `{ "items": [...], "next": ... }` (§5.4) |
|
|
222
258
|
| `create` | POST | `(body)` then optional `field = value` | 201 with the new record |
|
|
223
259
|
| `update` | PUT or PATCH | `(id, body)` | 200 with the updated record, or 404 |
|
|
224
260
|
| `delete` | DELETE | `(id)` | 204, or 404 |
|
|
225
261
|
|
|
226
262
|
**`list` arguments**, separated by commas:
|
|
227
263
|
- `field = value`: filters by equality, combined with AND.
|
|
228
|
-
- `order field` or `order field desc`: sorts. The default order is by `id`.
|
|
229
|
-
- `limit N`:
|
|
264
|
+
- `order field` or `order field desc`: sorts. The default order is by `id`. You can't order by an `optional` field, because pages need a sort value in every record.
|
|
265
|
+
- `limit N`: the largest page size, from 1 to 100. The default is 50.
|
|
230
266
|
|
|
231
267
|
Hidden fields (Password or `private`) cannot be used in filters or ordering.
|
|
232
268
|
|
|
@@ -252,7 +288,22 @@ The auth model itself cannot be created, updated or deleted through `api` blocks
|
|
|
252
288
|
|
|
253
289
|
Every path parameter must be used in the query (RZ0323).
|
|
254
290
|
|
|
255
|
-
### 5.4
|
|
291
|
+
### 5.4 Pages
|
|
292
|
+
|
|
293
|
+
A `list` endpoint returns one page at a time:
|
|
294
|
+
|
|
295
|
+
```
|
|
296
|
+
GET /posts?limit=10 → { "items": [ ...10 posts... ], "next": "WyJIZWxsbyIs..." }
|
|
297
|
+
GET /posts?limit=10&after=WyJI... → { "items": [ ...the next posts... ], "next": null }
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
- `limit` is optional. It must be a whole number from 1 to the endpoint's `limit`, which is also the default.
|
|
301
|
+
- `after` is the `next` value from the previous page. `next` is `null` on the last page.
|
|
302
|
+
- Pages continue exactly after the last record of the previous page, ordered by the sort field and then by `id`. Records added between requests can't cause records to be skipped or repeated.
|
|
303
|
+
- Cursors are opaque. Clients must not build or change them. An invalid cursor is rejected with 400.
|
|
304
|
+
- Endpoints accept no other query parameters. Any unknown or repeated parameter gets 400, on every endpoint.
|
|
305
|
+
|
|
306
|
+
### 5.5 A complete example
|
|
256
307
|
|
|
257
308
|
```rizo
|
|
258
309
|
auth User by email
|
|
@@ -303,6 +354,7 @@ api DELETE /posts/:id {
|
|
|
303
354
|
| `schema.sql` | PostgreSQL 13+ tables, constraints, foreign keys and the sessions table, inside one transaction |
|
|
304
355
|
| `types.ts` | `Model`, `ModelPublic` and `ModelInput` types for every model |
|
|
305
356
|
| `routes.ts` | Every endpoint as data, with its SQL written out in full |
|
|
357
|
+
| `migrate.ts`, `migrations/` | Applies the migrations from your project's `migrations/` folder (§6, Migrations) |
|
|
306
358
|
| `server.ts` | The entry point |
|
|
307
359
|
| `runtime/` | The Rizo runtime: validation, sessions, password hashing and the HTTP server |
|
|
308
360
|
| `package.json`, `tsconfig.json` | To install `pg` and type-check the app |
|
|
@@ -314,16 +366,46 @@ The three types:
|
|
|
314
366
|
- `UserPublic` (`User.public`) leaves out Password and `private` fields.
|
|
315
367
|
- `UserInput` (`User.input`) is what a client sends. Passwords are plain text here, and links to the auth model are left out.
|
|
316
368
|
|
|
369
|
+
### Migrations
|
|
370
|
+
|
|
371
|
+
Every build compares your models with the last build and records the difference in `migrations/`, next to your `.rz` file. Commit this folder to version control.
|
|
372
|
+
|
|
373
|
+
| File | Contents |
|
|
374
|
+
|------|----------|
|
|
375
|
+
| `migrations/0001_initial.sql` | The first schema |
|
|
376
|
+
| `migrations/0002_add_column_posts_views.sql`, … | One file per build that changed the schema |
|
|
377
|
+
| `migrations/rizo-schema.json` | A snapshot of the schema after the last migration. Don't edit it |
|
|
378
|
+
|
|
379
|
+
**Refused changes.** These changes would delete data, so the build stops (RZ0904) and writes no files, unless you run `rizolang build app.rz --allow-data-loss`:
|
|
380
|
+
- removing a model or field,
|
|
381
|
+
- changing a field's type,
|
|
382
|
+
- removing a role.
|
|
383
|
+
|
|
384
|
+
Renaming looks like removing and adding, so it is refused too. Keep the old name.
|
|
385
|
+
|
|
386
|
+
**Other changes** are generated automatically: adding models, fields and links, and changing limits, `unique`, `optional` and roles.
|
|
387
|
+
- Making a field required, adding a required field, or tightening limits can fail if existing rows don't fit.
|
|
388
|
+
- In that case the migration is rolled back and nothing changes.
|
|
389
|
+
|
|
390
|
+
**Applying migrations.** `node migrate.ts` (in `dist/`) applies pending migrations in order.
|
|
391
|
+
- Each migration runs in one transaction and is recorded in the `_rizo_migrations` table.
|
|
392
|
+
- A lock stops two deploys from migrating at the same time.
|
|
393
|
+
- If an applied migration file was edited or deleted, nothing runs.
|
|
394
|
+
|
|
395
|
+
**Existing databases.** If a database was created from `schema.sql` before you used migrations, run `node migrate.ts --baseline` once. It records `0001_initial.sql` as already applied.
|
|
396
|
+
|
|
317
397
|
### Running the server
|
|
318
398
|
|
|
319
399
|
Needs Node.js 22.18 or newer.
|
|
320
400
|
|
|
321
401
|
```sh
|
|
322
402
|
cd dist && npm install
|
|
323
|
-
|
|
403
|
+
DATABASE_URL=postgres://user:pass@localhost:5432/app node migrate.ts
|
|
324
404
|
DATABASE_URL=postgres://user:pass@localhost:5432/app node server.ts
|
|
325
405
|
```
|
|
326
406
|
|
|
407
|
+
To start a brand-new database, `psql "$DATABASE_URL" -f schema.sql` works too. Then run `node migrate.ts --baseline` so later migrations apply on top of it.
|
|
408
|
+
|
|
327
409
|
| Variable | Default | Meaning |
|
|
328
410
|
|-----------------------------|-------------|------------------------------------------------------------|
|
|
329
411
|
| `DATABASE_URL` | (required) | PostgreSQL connection string |
|
|
@@ -332,15 +414,17 @@ DATABASE_URL=postgres://user:pass@localhost:5432/app node server.ts
|
|
|
332
414
|
| `RIZO_TRUST_PROXY` | off | `1` to read the client IP from `X-Forwarded-For` (only behind a trusted proxy) |
|
|
333
415
|
| `RIZO_DEV_INSECURE_COOKIES` | off | `1` to drop the `Secure` cookie flag for local http. **Never in production.** |
|
|
334
416
|
| `RIZO_DB_POOL_SIZE` | `10` | Maximum number of database connections |
|
|
417
|
+
| `RIZO_ADMIN_EMAILS` | none | Comma-separated emails of **existing** accounts to make admins at startup (§4.1) |
|
|
335
418
|
|
|
336
419
|
### HTTP behaviour
|
|
337
420
|
|
|
338
421
|
- **Requests:**
|
|
422
|
+
- Only `list` endpoints accept query parameters (`limit` and `after`, §5.4). Any other query parameter gets 400.
|
|
339
423
|
- Bodies must be JSON (`Content-Type: application/json`) and at most 1 MB. Endpoints without `body` reject a request body.
|
|
340
424
|
- Path parameters are validated by type. An invalid id gets 400 before any query runs.
|
|
341
425
|
- **Responses** are JSON:
|
|
342
426
|
- Errors look like `{ "error": { "code": "...", "message": "...", "field": "..." } }`.
|
|
343
|
-
- Status codes: 400 invalid input, 401 not logged in, 403 cross-site request, 404 not found, 405 wrong method, 409 duplicate or still in use, 413 too large, 415 not JSON, 429 too many attempts, 500 internal error (with a request id).
|
|
427
|
+
- Status codes: 400 invalid input, 401 not logged in, 403 cross-site request or missing role, 404 not found, 405 wrong method, 409 duplicate or still in use, 413 too large, 415 not JSON, 429 too many attempts, 500 internal error (with a request id).
|
|
344
428
|
- Every response carries `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` and a `Content-Security-Policy` that allows nothing.
|
|
345
429
|
- **Cross-site requests:** POST, PUT, PATCH and DELETE requests with an `Origin` header from another site are rejected with 403.
|
|
346
430
|
- **Logs:** one line per request: the method, the route pattern (such as `/posts/:id`), the status, the time and a request id. Logs never contain URLs with values, bodies, cookies or passwords.
|
|
@@ -355,10 +439,10 @@ These are enforced by the compiler and the runtime, and covered by `tests/securi
|
|
|
355
439
|
2. A Password is never stored in plain text.
|
|
356
440
|
3. All SQL is written at compile time. Request data only fills `$1, $2, …` parameters, and names can't break out of their quotes.
|
|
357
441
|
4. Every endpoint declares its access, and `requires owner` is enforced inside the query. Records that belong to a user can only be changed or deleted by that user.
|
|
358
|
-
5. A record's owner is always the logged-in user.
|
|
442
|
+
5. A record's owner is always the logged-in user, and a user's role is only ever set by an admin. Neither is taken from the request body.
|
|
359
443
|
6. All input is validated against the model before it reaches the database, and unknown fields are rejected.
|
|
360
444
|
7. `GET` endpoints never change data. Cross-site writes are rejected.
|
|
361
|
-
8. When there is any compile error, no output is written.
|
|
445
|
+
8. When there is any compile error, or a change would delete data without `--allow-data-loss`, no output is written.
|
|
362
446
|
|
|
363
447
|
---
|
|
364
448
|
|
|
@@ -397,6 +481,7 @@ app.rz:3:9 error RZ0301: Unknown field type "String" on field "User.name".
|
|
|
397
481
|
| RZ0216 | Unknown statement in an `api` block |
|
|
398
482
|
| RZ0217 | Invalid query syntax |
|
|
399
483
|
| RZ0218 | Invalid `auth` line |
|
|
484
|
+
| RZ0219 | Missing role name in a role list |
|
|
400
485
|
| RZ0301 | Unknown field type |
|
|
401
486
|
| RZ0302 | Modifier not allowed on this type |
|
|
402
487
|
| RZ0303 | Modifier repeated |
|
|
@@ -428,9 +513,12 @@ app.rz:3:9 error RZ0301: Unknown field type "String" on field "User.name".
|
|
|
428
513
|
| RZ0329 | Invalid `requires owner` |
|
|
429
514
|
| RZ0330 | `me` used in a public endpoint |
|
|
430
515
|
| RZ0331 | `update` or `delete` of an owned record without `requires owner` |
|
|
516
|
+
| RZ0332 | Unknown role, or roles used without declaring them |
|
|
431
517
|
| RZ0901 | Cannot read the input file |
|
|
432
518
|
| RZ0902 | Input file does not end in `.rz` |
|
|
433
519
|
| RZ0903 | Wrong command-line usage |
|
|
520
|
+
| RZ0904 | The change would delete data (needs `--allow-data-loss`) |
|
|
521
|
+
| RZ0905 | `migrations/rizo-schema.json` is missing or damaged |
|
|
434
522
|
|
|
435
523
|
---
|
|
436
524
|
|
|
@@ -569,13 +657,14 @@ model = "model" NAME "{" { field } "}" ;
|
|
|
569
657
|
field = NAME ":" TYPE { modifier } NEWLINE ;
|
|
570
658
|
modifier = "unique" | "optional" | "private" | "min" INT | "max" INT ;
|
|
571
659
|
TYPE = "Text" | "Number" | "Bool" | "Email" | "Password" | "Date" | "ID" | NAME ;
|
|
572
|
-
auth = "auth" NAME "by" NAME NEWLINE ;
|
|
660
|
+
auth = "auth" NAME "by" NAME [ "roles" NAME { "," NAME } ] NEWLINE ;
|
|
573
661
|
api = "api" METHOD PATH [ "->" rettype ] "{" { statement NEWLINE } "}" ;
|
|
574
662
|
METHOD = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" ;
|
|
575
663
|
PATH = "/" [ segment { "/" segment } ] ;
|
|
576
664
|
segment = LOWER { LOWER | DIGIT | "-" } | ":" NAME ;
|
|
577
665
|
rettype = [ "list" ] NAME "." "public" ;
|
|
578
|
-
statement = "public" | "requires" "login" | "requires" "
|
|
666
|
+
statement = "public" | "requires" "login" | "requires" "role" NAME { "," NAME }
|
|
667
|
+
| "requires" "owner" NAME [ "or" "role" NAME { "," NAME } ] | "return" query ;
|
|
579
668
|
query = "db" "." NAME "." ACTION "(" [ arg { "," arg } ] ")" ;
|
|
580
669
|
ACTION = "find" | "list" | "create" | "update" | "delete" ;
|
|
581
670
|
arg = NAME | NAME "=" value | "order" NAME [ "asc" | "desc" ] | "limit" INT ;
|
|
@@ -591,7 +680,6 @@ comment = "//" { any character except newline } ;
|
|
|
591
680
|
|
|
592
681
|
These are **not** part of the language yet. Using them is an error.
|
|
593
682
|
|
|
594
|
-
- Roles (`requires role admin`).
|
|
595
683
|
- Pagination, and filters other than `=`.
|
|
596
|
-
- Changing
|
|
684
|
+
- Changing the login email, and password reset by email (these need email verification).
|
|
597
685
|
- Frontend `page` blocks.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rizolang",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"description": "Rizo Lang: a secure, simple, full-stack web language for the AI era. Compiles to PostgreSQL and TypeScript.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"homepage": "https://rizobot.com",
|
|
@@ -46,5 +46,8 @@
|
|
|
46
46
|
"pg": "8.23.1",
|
|
47
47
|
"typescript": "7.0.2",
|
|
48
48
|
"vitest": "5.1.0"
|
|
49
|
+
},
|
|
50
|
+
"publishConfig": {
|
|
51
|
+
"access": "public"
|
|
49
52
|
}
|
|
50
53
|
}
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Rizo Lang runtime: applies the SQL files in migrations/ to the database.
|
|
3
|
+
*
|
|
4
|
+
* - Each migration runs in its own transaction and is recorded in
|
|
5
|
+
* "_rizo_migrations" with a checksum, so it is applied exactly once.
|
|
6
|
+
* - A PostgreSQL advisory lock stops two deploys from migrating at once.
|
|
7
|
+
* - If an applied migration file was changed or deleted, nothing runs.
|
|
8
|
+
*/
|
|
9
|
+
import { createHash } from "node:crypto";
|
|
10
|
+
import { readFileSync, readdirSync } from "node:fs";
|
|
11
|
+
import { fileURLToPath } from "node:url";
|
|
12
|
+
import pg from "pg";
|
|
13
|
+
|
|
14
|
+
export const MIGRATIONS_TABLE = '"_rizo_migrations"';
|
|
15
|
+
const MIGRATION_FILE = /^\d{4}_[a-z0-9_]+\.sql$/;
|
|
16
|
+
/** Arbitrary constant identifying the rizolang migration lock. */
|
|
17
|
+
const LOCK_ID = 727_201_401;
|
|
18
|
+
|
|
19
|
+
export interface Migration {
|
|
20
|
+
readonly name: string;
|
|
21
|
+
readonly sql: string;
|
|
22
|
+
readonly checksum: string;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export interface MigrateResult {
|
|
26
|
+
readonly applied: readonly string[];
|
|
27
|
+
readonly baselined: string | undefined;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** Read the migration files of a directory, in order. */
|
|
31
|
+
export function readMigrations(dir: string): Migration[] {
|
|
32
|
+
return readdirSync(dir)
|
|
33
|
+
.filter((f) => MIGRATION_FILE.test(f))
|
|
34
|
+
.sort()
|
|
35
|
+
.map((name) => {
|
|
36
|
+
const sql = readFileSync(`${dir}/${name}`, "utf8");
|
|
37
|
+
return { name, sql, checksum: createHash("sha256").update(sql).digest("hex") };
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export class MigrationError extends Error {}
|
|
42
|
+
|
|
43
|
+
/** A connected client, e.g. a `pg.Client` or a client from a pool. */
|
|
44
|
+
export interface MigrationClient {
|
|
45
|
+
query(sql: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Apply pending migrations. With `baseline`, the first migration is recorded
|
|
50
|
+
* as applied without running it (for databases created from schema.sql).
|
|
51
|
+
*/
|
|
52
|
+
export async function migrate(client: MigrationClient, migrations: readonly Migration[], options: { baseline?: boolean } = {}): Promise<MigrateResult> {
|
|
53
|
+
await client.query("SELECT pg_advisory_lock($1)", [LOCK_ID]);
|
|
54
|
+
try {
|
|
55
|
+
await client.query(
|
|
56
|
+
`CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} ("name" TEXT PRIMARY KEY, "checksum" TEXT NOT NULL, "applied_at" TIMESTAMPTZ NOT NULL DEFAULT now())`,
|
|
57
|
+
);
|
|
58
|
+
const done = new Map(
|
|
59
|
+
(await client.query(`SELECT "name", "checksum" FROM ${MIGRATIONS_TABLE}`)).rows.map((r) => [String(r["name"]), String(r["checksum"])]),
|
|
60
|
+
);
|
|
61
|
+
for (const [name, checksum] of done) {
|
|
62
|
+
const file = migrations.find((m) => m.name === name);
|
|
63
|
+
if (file === undefined) throw new MigrationError(`Migration ${name} was applied to this database but its file is missing. Restore it from version control.`);
|
|
64
|
+
if (file.checksum !== checksum) {
|
|
65
|
+
throw new MigrationError(`Migration ${name} was changed after it was applied. Restore the original file and put new changes in a new migration.`);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
let baselined: string | undefined;
|
|
70
|
+
if (options.baseline) {
|
|
71
|
+
const first = migrations[0];
|
|
72
|
+
if (done.size > 0) throw new MigrationError("--baseline is only for a database that has no migrations recorded yet.");
|
|
73
|
+
if (first === undefined) throw new MigrationError("There are no migrations to baseline.");
|
|
74
|
+
await client.query(`INSERT INTO ${MIGRATIONS_TABLE} ("name", "checksum") VALUES ($1, $2)`, [first.name, first.checksum]);
|
|
75
|
+
done.set(first.name, first.checksum);
|
|
76
|
+
baselined = first.name;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const applied: string[] = [];
|
|
80
|
+
for (const m of migrations) {
|
|
81
|
+
if (done.has(m.name)) continue;
|
|
82
|
+
await client.query("BEGIN");
|
|
83
|
+
try {
|
|
84
|
+
await client.query(m.sql);
|
|
85
|
+
await client.query(`INSERT INTO ${MIGRATIONS_TABLE} ("name", "checksum") VALUES ($1, $2)`, [m.name, m.checksum]);
|
|
86
|
+
await client.query("COMMIT");
|
|
87
|
+
} catch (e) {
|
|
88
|
+
await client.query("ROLLBACK");
|
|
89
|
+
const reason = e instanceof Error ? e.message : String(e);
|
|
90
|
+
throw new MigrationError(
|
|
91
|
+
`Migration ${m.name} failed and was rolled back: ${reason}` +
|
|
92
|
+
(/null values|violates check|could not create unique/.test(reason)
|
|
93
|
+
? "\nExisting rows do not fit the new rules. Fix or remove those rows, or make the field optional, then run again."
|
|
94
|
+
: ""),
|
|
95
|
+
);
|
|
96
|
+
}
|
|
97
|
+
applied.push(m.name);
|
|
98
|
+
}
|
|
99
|
+
return { applied, baselined };
|
|
100
|
+
} finally {
|
|
101
|
+
await client.query("SELECT pg_advisory_unlock($1)", [LOCK_ID]);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** Entry point used by the generated migrate.ts. */
|
|
106
|
+
export async function runMigrations(dirUrl: URL): Promise<void> {
|
|
107
|
+
const url = process.env["DATABASE_URL"];
|
|
108
|
+
if (url === undefined || url === "") {
|
|
109
|
+
process.stderr.write("rizo: DATABASE_URL is not set.\n fix: Run DATABASE_URL=postgres://user:password@localhost:5432/app node migrate.ts\n");
|
|
110
|
+
process.exit(1);
|
|
111
|
+
}
|
|
112
|
+
const args = process.argv.slice(2);
|
|
113
|
+
const unknown = args.find((a) => a !== "--baseline");
|
|
114
|
+
if (unknown !== undefined) {
|
|
115
|
+
process.stderr.write(`rizo: unknown option "${unknown}". The only option is --baseline.\n`);
|
|
116
|
+
process.exit(1);
|
|
117
|
+
}
|
|
118
|
+
const client = new pg.Client({ connectionString: url });
|
|
119
|
+
await client.connect();
|
|
120
|
+
try {
|
|
121
|
+
const r = await migrate(client, readMigrations(fileURLToPath(dirUrl)), { baseline: args.includes("--baseline") });
|
|
122
|
+
if (r.baselined !== undefined) process.stdout.write(`rizo: recorded ${r.baselined} as already applied (baseline)\n`);
|
|
123
|
+
for (const name of r.applied) process.stdout.write(`rizo: applied ${name}\n`);
|
|
124
|
+
if (r.applied.length === 0) process.stdout.write("rizo: database is up to date\n");
|
|
125
|
+
} catch (e) {
|
|
126
|
+
process.stderr.write(`rizo: ${e instanceof Error ? e.message : String(e)}\n`);
|
|
127
|
+
process.exitCode = 1;
|
|
128
|
+
} finally {
|
|
129
|
+
await client.end();
|
|
130
|
+
}
|
|
131
|
+
}
|