ramdb2-cli 2.0.0-alpha.0 → 2.0.0-alpha.10
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/CHANGELOG.md +55 -0
- package/README.md +187 -2
- package/package.json +5 -4
- package/src/cli.js +114 -2
- package/src/directives.js +6 -3
- package/src/generate/classes.js +29 -0
- package/src/generate/client.js +14 -6
- package/src/generate/typeDefs.js +16 -2
- package/src/generate.js +45 -7
- package/src/index.js +6 -0
- package/src/infra/backups.js +77 -0
- package/src/infra/build.js +372 -0
- package/src/infra/config.js +165 -0
- package/src/infra/deploy.js +41 -0
- package/src/infra/down.js +19 -0
- package/src/infra/keygen.js +54 -0
- package/src/infra/server.js +106 -0
- package/src/model.js +41 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# ramdb2-cli
|
|
2
|
+
|
|
3
|
+
## 2.0.0-alpha.10
|
|
4
|
+
|
|
5
|
+
No changes in this release.
|
|
6
|
+
|
|
7
|
+
## 2.0.0-alpha.9
|
|
8
|
+
|
|
9
|
+
No changes in this release.
|
|
10
|
+
|
|
11
|
+
## 2.0.0-alpha.8
|
|
12
|
+
|
|
13
|
+
No changes in this release.
|
|
14
|
+
|
|
15
|
+
## 2.0.0-alpha.7
|
|
16
|
+
|
|
17
|
+
### Minor Changes
|
|
18
|
+
|
|
19
|
+
- 8fa4d07: `@transient(getter: true)`: a getter of the class gives the value of the field, so a query filters and sorts on it (`static transientGetters`), and `RdbCrud` sorts its column by default. ramdb2-server refuses to start when the getter is missing, and refuses in a query a `@transient` resolved by GraphQL only (D62).
|
|
20
|
+
|
|
21
|
+
## 2.0.0-alpha.6
|
|
22
|
+
|
|
23
|
+
No changes in this release.
|
|
24
|
+
|
|
25
|
+
## 2.0.0-alpha.5
|
|
26
|
+
|
|
27
|
+
### Minor Changes
|
|
28
|
+
|
|
29
|
+
- e34f3bd: `generate` and `client` remove the generated classes of a type gone from the schema, and name its extended class in a warning (D61).
|
|
30
|
+
|
|
31
|
+
## 2.0.0-alpha.4
|
|
32
|
+
|
|
33
|
+
### Minor Changes
|
|
34
|
+
|
|
35
|
+
- 919e6ae: Permissions by field (D58): `@restricted` in the schema, `permissions.<Type>.fields` in ramdb2-server. A refused field gives `null`; a query on a restricted field only covers the objects whose field the user may read.
|
|
36
|
+
- a26c413: The `see` permission applies to the relations (D57): a list relation is filtered, an object relation the user cannot see gives `null`. `ramdb2-cli generate` serves the object relations as nullable; `ramdb2-cli client` types them `Xxx | null`.
|
|
37
|
+
|
|
38
|
+
## 2.0.0-alpha.3
|
|
39
|
+
|
|
40
|
+
### Minor Changes
|
|
41
|
+
|
|
42
|
+
- 92570bd: `ramdb2-cli infra down <server>`: stops a server (docker compose down), keeps its volumes; asks first, unless `--yes`.
|
|
43
|
+
|
|
44
|
+
## 2.0.0-alpha.2
|
|
45
|
+
|
|
46
|
+
### Minor Changes
|
|
47
|
+
|
|
48
|
+
- 989ba8b: `ramdb2-cli infra deploy <server>`: build, secrets decrypted by sops, `docker compose up` on the server through `DOCKER_HOST`, Let's Encrypt certificates, nginx reloaded.
|
|
49
|
+
- ee78e45: `ramdb2-cli infra keygen`, `infra backups`, `infra restore` and `infra fetch`: the backup key of a server, encrypted by sops; the backups of a site listed, restored or fetched through its server.
|
|
50
|
+
|
|
51
|
+
## 2.0.0-alpha.1
|
|
52
|
+
|
|
53
|
+
### Minor Changes
|
|
54
|
+
|
|
55
|
+
- 14d1f42: `ramdb2-cli infra build`: the Docker files of each server from `infra.yaml`, a front nginx with HTTPS and one domain per site, the API, its backups and the web site of each ramdb2 project.
|
package/README.md
CHANGED
|
@@ -42,12 +42,16 @@ Several `--schema` files are read as one schema. In a project created by `ramdb2
|
|
|
42
42
|
| `db/generated/<table>.js` | class `XxxBase`: fields, foreign keys, indexes, rules, default values, getters and setters, relations, computed fields, finders, invalidation code | at each generation |
|
|
43
43
|
| `db/extended/<table>.js` | class `Xxx extends XxxBase`: your business rules, computed fields and methods | never: created when missing |
|
|
44
44
|
| `db/index.js` | the extended classes, and `classes` for `store.register(...classes)` | at each generation |
|
|
45
|
-
| `schema/typeDefs.graphql` | the schema served by the API: without the directives (but `@sensitive`) nor the `@private` fields, with `id` and the foreign keys | at each generation |
|
|
45
|
+
| `schema/typeDefs.graphql` | the schema served by the API: without the directives (but `@sensitive`) nor the `@private` fields, with `id` and the foreign keys; a field that leads to one persistent object is nullable, as the `see` permission may hide it, and so is a `@restricted` field | at each generation |
|
|
46
46
|
| `schema/operations.graphql` | the `JSON` scalar, and for each type its input (with the `@sensitive` fields, without the `@private` ones), validation, query and list types, its queries and mutations | at each generation |
|
|
47
47
|
|
|
48
48
|
Never edit a generated file: the next generation would erase the change. Everything you write goes in
|
|
49
49
|
`db/extended`, and in your own schema files (`extend type Query { ... }`).
|
|
50
50
|
|
|
51
|
+
When a type leaves the schema, its file in `db/generated/` is removed (`removed` in the output); only a file with
|
|
52
|
+
the header `// Generated by ramdb2-cli` is ever removed. Its file in `db/extended/`, written by you, is kept and
|
|
53
|
+
named in a warning. `client` does the same in its `generated/` and `extended/` folders.
|
|
54
|
+
|
|
51
55
|
### The schema: the preTypeDefs
|
|
52
56
|
|
|
53
57
|
```graphql
|
|
@@ -96,9 +100,10 @@ a directive in the wrong place, a missing or badly typed argument is an error.
|
|
|
96
100
|
| `@onDelete` | list | `action: CASCADE \| SET_ZERO \| RESTRICT \| NOTHING` | deletion policy of these objects |
|
|
97
101
|
| `@computed` | field | `depends: [String!]!` | a cached value, with the paths it depends on |
|
|
98
102
|
| `@pattern` | field | `regex: String!`, `message: String` | a validation rule |
|
|
99
|
-
| `@transient` | field | | a field of the API that is not stored |
|
|
103
|
+
| `@transient` | field | `getter: Boolean = false` | a field of the API that is not stored. `getter: true`: a getter of the class gives its value (written in the extended class), so a query filters and sorts on it, and ramdb2-server checks the getter at start. A scalar without arguments. Not indexed: a query reads the getter on every candidate object |
|
|
100
104
|
| `@sensitive` | field | | its value is masked in the logs of ramdb2-server (`"[REDACTED]"`) |
|
|
101
105
|
| `@private` | field | | stored and read by your code, but absent from the API: neither read, written nor queried (a password hash). Not with `!` when it would be required, nor with a FULLTEXT index |
|
|
106
|
+
| `@restricted` | field | | read through the API only when its permission allows it, object by object (`permissions.<Type>.fields` of ramdb2-server); served nullable. On a stored field, an object relation (with its foreign key), a computed or `@transient` field. A computed field that depends on it must be `@restricted` too |
|
|
102
107
|
|
|
103
108
|
### How the fields are read
|
|
104
109
|
|
|
@@ -258,6 +263,7 @@ as for `generate`). It writes, in `--dest`:
|
|
|
258
263
|
API.
|
|
259
264
|
- `transient`: the `@transient` fields of a scalar type (scalar, enum, custom scalar, list of them), always loaded
|
|
260
265
|
with the object. One of an object type, or with a required argument, is left out with a warning.
|
|
266
|
+
- `transientGetters`: the `@transient(getter: true)` fields, sorted by default in a `RdbCrud`.
|
|
261
267
|
- `fullText`: the fields of the `FULLTEXT` index, in the order of the schema (`[]` without one), for a search with `$text`.
|
|
262
268
|
- `generatedRules`: the same rules as the server (`required`, `pattern`, `oneOf`), plus `requiredKey('idProject')`
|
|
263
269
|
for a required object relation.
|
|
@@ -357,6 +363,185 @@ each list relation to check; write an `@onDelete` where the policy is not the de
|
|
|
357
363
|
|
|
358
364
|
---
|
|
359
365
|
|
|
366
|
+
## infra
|
|
367
|
+
|
|
368
|
+
The servers of your sites, in Docker: one front nginx per server (HTTPS, one domain per site), and for each ramdb2
|
|
369
|
+
site its API, its backups and its web site. Only Docker is needed on the server: the images are built there, from
|
|
370
|
+
your machine, with `DOCKER_HOST=ssh://`.
|
|
371
|
+
|
|
372
|
+
```sh
|
|
373
|
+
ramdb2-cli infra build # build/<server>/ for every server of ./infra.yaml
|
|
374
|
+
ramdb2-cli infra build ovh1 # one server
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
An infra folder (a git repository of its own):
|
|
378
|
+
|
|
379
|
+
| Path | Content |
|
|
380
|
+
|---|---|
|
|
381
|
+
| `infra.yaml` | the backups, the servers and their sites |
|
|
382
|
+
| `custom/<name>.nginx.conf`, `custom/<name>.compose.yaml` | a site that is not a ramdb2 project, written by hand |
|
|
383
|
+
| `build/` | generated, rewritten by each build: keep it out of git |
|
|
384
|
+
|
|
385
|
+
```yaml
|
|
386
|
+
backup:
|
|
387
|
+
target: sftp://backup@backups.example.org:22/ramdb2 # one folder per site under it
|
|
388
|
+
servers:
|
|
389
|
+
ovh1:
|
|
390
|
+
host: ssh://manu@ovh1.example.org
|
|
391
|
+
email: me@example.org # the Let's Encrypt account
|
|
392
|
+
sites:
|
|
393
|
+
ilife: # unique on all the servers: containers, volume, backup folder
|
|
394
|
+
source: ../ilife # the project, made by ramdb2-cli new, relative to infra.yaml
|
|
395
|
+
domain: ilife.fr
|
|
396
|
+
aliases: [www.ilife.fr] # redirected (301) to domain
|
|
397
|
+
memory: 512m
|
|
398
|
+
custom:
|
|
399
|
+
- gancio # custom/gancio.nginx.conf, and custom/gancio.compose.yaml if any
|
|
400
|
+
- name: wiki
|
|
401
|
+
domains: [wiki.example.org] # certbot keeps a certificate, in /etc/nginx/certs/wiki.example.org/
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
All the errors of `infra.yaml` are reported at once. `build/<server>/` holds:
|
|
405
|
+
|
|
406
|
+
| File | Content |
|
|
407
|
+
|---|---|
|
|
408
|
+
| `compose.yaml` | the Compose project of the server, the custom compose files included |
|
|
409
|
+
| `nginx/` | the front nginx image: its configuration, one file per site, the custom ones copied |
|
|
410
|
+
| `<site>/api.Dockerfile` | the API (target `api`, `node src/index.js`) and its backups (target `backup`, `ramdb2-server-backup schedule`) |
|
|
411
|
+
| `<site>/web.Dockerfile` | for a project made with `--with-client`: the site compiled by Vite, served by nginx |
|
|
412
|
+
| `certificates.json` | the certificates of the server and their domains |
|
|
413
|
+
|
|
414
|
+
- Each domain: HTTP redirected to HTTPS, `/graphql` to the API, the rest to the web site (all to the API for a
|
|
415
|
+
project without a web site).
|
|
416
|
+
- The database lives in a Docker volume, `<site>-data`. The images never contain `node_modules` from your machine,
|
|
417
|
+
a database, a backup or a `.env`.
|
|
418
|
+
- Nothing is mounted from your machine: the nginx configuration is in its image; the secrets come from the
|
|
419
|
+
environment of `docker compose` (`RAMDB2_SECRETS`, the folder of the site `.env` files, and `BACKUP_SSH_KEY`).
|
|
420
|
+
- The healthcheck of the API sends the GraphQL query `health`: keep it open without a login.
|
|
421
|
+
- Until a certificate exists, nginx serves a self-signed one, so that it can start.
|
|
422
|
+
|
|
423
|
+
### Deploy
|
|
424
|
+
|
|
425
|
+
```sh
|
|
426
|
+
ramdb2-cli infra deploy ovh1 # build, then up on the server, then the certificates
|
|
427
|
+
ramdb2-cli infra deploy ovh1 --staging # with the test certificates of Let's Encrypt
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
The secrets live in the infra folder, encrypted by [sops](https://github.com/getsops/sops) (with
|
|
431
|
+
[age](https://github.com/FiloSottile/age) keys listed in `.sops.yaml`):
|
|
432
|
+
|
|
433
|
+
| File | Content |
|
|
434
|
+
|---|---|
|
|
435
|
+
| `secrets/<site>.env` | the environment of the API of a site (`TOKEN_SECRET`…) |
|
|
436
|
+
| `secrets/<server>.key` | the private SSH key of the server, for its backups |
|
|
437
|
+
|
|
438
|
+
`deploy` needs `docker`, `sops` and an SSH access to the server on your machine. It:
|
|
439
|
+
|
|
440
|
+
1. runs `build` for the server;
|
|
441
|
+
2. decrypts the secrets into a private temporary folder, deleted at the end;
|
|
442
|
+
3. runs `docker compose up -d --build --remove-orphans` with `DOCKER_HOST` set to the `host` of the server: the
|
|
443
|
+
images are built on the server;
|
|
444
|
+
4. asks Let's Encrypt for each certificate (nothing is done while a certificate is valid; it is made again when
|
|
445
|
+
its domains change), then reloads nginx.
|
|
446
|
+
|
|
447
|
+
It stops before Docker when a secret is missing or cannot be decrypted. A refused certificate (a domain that does
|
|
448
|
+
not point to the server yet) does not stop the others; the exit code is then 1.
|
|
449
|
+
|
|
450
|
+
The decrypted secrets live in `build/<server>/.secrets-*` (only you can read it) while a command runs, and are
|
|
451
|
+
deleted at the end, even on an error. Not in `/tmp`: Docker installed as a snap cannot read it.
|
|
452
|
+
|
|
453
|
+
### Stop a server
|
|
454
|
+
|
|
455
|
+
```sh
|
|
456
|
+
ramdb2-cli infra down ovh1 # asks first; --yes to skip the question
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
`down` runs `docker compose down --remove-orphans` on the server: the containers of all its sites (ramdb2 and
|
|
460
|
+
custom) and its network are removed. The volumes (the databases, the backup queues), the images and the
|
|
461
|
+
certificates stay: `ramdb2-cli infra deploy ovh1` starts the server again as it was. Like every command that talks
|
|
462
|
+
to a server, it decrypts the secrets: Compose needs them to read `compose.yaml`.
|
|
463
|
+
|
|
464
|
+
### Secrets: sops and age, once
|
|
465
|
+
|
|
466
|
+
```sh
|
|
467
|
+
age-keygen -o ~/.config/sops/age/keys.txt # your age key, where sops looks for it
|
|
468
|
+
age-keygen -y ~/.config/sops/age/keys.txt # its public key, for .sops.yaml
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
`.sops.yaml`, at the root of the infra folder:
|
|
472
|
+
|
|
473
|
+
```yaml
|
|
474
|
+
creation_rules:
|
|
475
|
+
- path_regex: secrets/.*
|
|
476
|
+
age: age1...your public key...
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
Keep a copy of your age key somewhere safe (a password manager): without it, no secret can be decrypted, and no
|
|
480
|
+
server can be deployed. Then the secrets of a site:
|
|
481
|
+
|
|
482
|
+
```sh
|
|
483
|
+
sops secrets/ilife.env # opens your editor; saved encrypted. TOKEN_SECRET=..., one variable per line
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
### The backup key of a server
|
|
487
|
+
|
|
488
|
+
```sh
|
|
489
|
+
ramdb2-cli infra keygen ovh1
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
Creates an SSH key for the backups of the server: `secrets/ovh1.key`, encrypted by sops, and `secrets/ovh1.pub`.
|
|
493
|
+
It prints the line to add to `~backup/.ssh/authorized_keys` on the backup server:
|
|
494
|
+
`restrict ssh-ed25519 AAAA... ramdb2-backup-ovh1`. An existing key is replaced only with `--force`; install the
|
|
495
|
+
new public key then, and deploy again.
|
|
496
|
+
|
|
497
|
+
### The backup server
|
|
498
|
+
|
|
499
|
+
Any OpenSSH server. A user `backup`, which can only use SFTP, locked in the backup folder, with keys only. In
|
|
500
|
+
`/etc/ssh/sshd_config`:
|
|
501
|
+
|
|
502
|
+
```
|
|
503
|
+
PasswordAuthentication no
|
|
504
|
+
KbdInteractiveAuthentication no
|
|
505
|
+
Subsystem sftp internal-sftp
|
|
506
|
+
|
|
507
|
+
Match User backup
|
|
508
|
+
ChrootDirectory /volume1/backup
|
|
509
|
+
ForceCommand internal-sftp
|
|
510
|
+
AllowTcpForwarding no
|
|
511
|
+
X11Forwarding no
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
- The chroot folder (`/volume1/backup`) belongs to root and only root can write it (an OpenSSH rule); the folder
|
|
515
|
+
of the backups inside it (`ramdb2`) belongs to `backup`.
|
|
516
|
+
- `backup.target` in `infra.yaml` is then `sftp://backup@host:22/ramdb2`: the path is seen from the chroot.
|
|
517
|
+
- Each server key sees the backups of every site: a site can move to another server and keep its backups.
|
|
518
|
+
- The first connection of a server accepts the host key of the backup server, then checks it.
|
|
519
|
+
|
|
520
|
+
### Backups and restore
|
|
521
|
+
|
|
522
|
+
Each ramdb2 site has its backup container: a compressed image of the database every 5 minutes, sent to the
|
|
523
|
+
backup server, then pruned there (every backup of the last 24 hours, the last of each day for 30 days, the last of
|
|
524
|
+
each month forever). See [`ramdb2-server-backup`](https://www.npmjs.com/package/ramdb2-server). From your machine:
|
|
525
|
+
|
|
526
|
+
```sh
|
|
527
|
+
ramdb2-cli infra backups ilife # the backups of the site, oldest first
|
|
528
|
+
ramdb2-cli infra restore ilife # the most recent backup
|
|
529
|
+
ramdb2-cli infra restore ilife 2026-11-06T14:00 # the last one at or before that moment (UTC)
|
|
530
|
+
ramdb2-cli infra fetch ilife ilife.db # the most recent backup, to a local file
|
|
531
|
+
ramdb2-cli infra fetch ilife ilife.db 2026-11-06T14:00
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
- The server of a site is read in `infra.yaml`. The commands run on it, in the backup container of the site, with
|
|
535
|
+
the key of the server: your machine needs no access to the backup server.
|
|
536
|
+
- `restore` asks first (`--yes` to skip the question). It stops the API and the backups of the site, checks the
|
|
537
|
+
backup (`PRAGMA integrity_check`), replaces the database, then starts them again; when the backup is damaged,
|
|
538
|
+
the database is left as it was and the site starts again.
|
|
539
|
+
- A new server: install Docker, `ramdb2-cli infra deploy <server>`, then `ramdb2-cli infra restore <site>` for each
|
|
540
|
+
site.
|
|
541
|
+
- `fetch` writes a database you can open with any SQLite tool, or use as `DB_PATH` of the project on your machine.
|
|
542
|
+
|
|
543
|
+
---
|
|
544
|
+
|
|
360
545
|
## Programmatic use
|
|
361
546
|
|
|
362
547
|
```js
|
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ramdb2-cli",
|
|
3
|
-
"version": "2.0.0-alpha.
|
|
3
|
+
"version": "2.0.0-alpha.10",
|
|
4
4
|
"description": "Code generator and project scaffolding for ramdb2 and ramdb2-server",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": "./src/index.js",
|
|
7
7
|
"bin": {
|
|
8
|
-
"ramdb2-cli": "
|
|
8
|
+
"ramdb2-cli": "src/cli.js"
|
|
9
9
|
},
|
|
10
10
|
"license": "MIT",
|
|
11
11
|
"author": "Emmanuel Leparquier",
|
|
@@ -23,11 +23,12 @@
|
|
|
23
23
|
"test": "node --test \"test/**/*.test.js\""
|
|
24
24
|
},
|
|
25
25
|
"dependencies": {
|
|
26
|
-
"graphql": "^16.14.2"
|
|
26
|
+
"graphql": "^16.14.2",
|
|
27
|
+
"yaml": "^2.9.1"
|
|
27
28
|
},
|
|
28
29
|
"devDependencies": {
|
|
29
|
-
"ramdb2-core": "^2.0.0-alpha.0",
|
|
30
30
|
"@vitejs/plugin-vue": "^6.0.10",
|
|
31
|
+
"ramdb2-core": "^2.0.0-alpha.10",
|
|
31
32
|
"vite": "^8.3.5",
|
|
32
33
|
"vue": "^3.5.44",
|
|
33
34
|
"vue-router": "^5.4.0"
|
package/src/cli.js
CHANGED
|
@@ -6,6 +6,13 @@ import { convert } from './convert.js'
|
|
|
6
6
|
import { newProject } from './new.js'
|
|
7
7
|
import { plantuml } from './plantuml.js'
|
|
8
8
|
import { query } from './query.js'
|
|
9
|
+
import { readInfra } from './infra/config.js'
|
|
10
|
+
import { buildInfra } from './infra/build.js'
|
|
11
|
+
import { deploy } from './infra/deploy.js'
|
|
12
|
+
import { down } from './infra/down.js'
|
|
13
|
+
import { keygen } from './infra/keygen.js'
|
|
14
|
+
import { fetch as fetchBackup, listBackups, restore } from './infra/backups.js'
|
|
15
|
+
import { createInterface } from 'node:readline/promises'
|
|
9
16
|
|
|
10
17
|
const HELP = `ramdb2-cli: code generator of ramdb2
|
|
11
18
|
|
|
@@ -35,11 +42,47 @@ const HELP = `ramdb2-cli: code generator of ramdb2
|
|
|
35
42
|
--packages: the packages folder of a ramdb2 repository, to depend on it through file: paths
|
|
36
43
|
(default: the packages from npm, at the version of this ramdb2-cli).
|
|
37
44
|
|
|
45
|
+
ramdb2-cli infra build [<server>...] [--config <infra.yaml>]
|
|
46
|
+
Writes build/<server>/ next to infra.yaml (all the servers by default): compose.yaml, the front nginx,
|
|
47
|
+
the Dockerfiles of each site. Generated, rewritten each time: keep build/ out of git.
|
|
48
|
+
|
|
49
|
+
ramdb2-cli infra deploy <server> [--staging] [--config <infra.yaml>]
|
|
50
|
+
build, then the secrets decrypted by sops (secrets/<site>.env, secrets/<server>.key), docker compose up
|
|
51
|
+
on the server (DOCKER_HOST=ssh://...), the missing Let's Encrypt certificates, and nginx reloaded.
|
|
52
|
+
--staging: the test certificates of Let's Encrypt, not trusted by browsers.
|
|
53
|
+
|
|
54
|
+
ramdb2-cli infra down <server> [--yes]
|
|
55
|
+
Stops the server: docker compose down, its containers and its network removed. The volumes (the
|
|
56
|
+
databases), the images and the certificates stay: infra deploy starts it again. Asks first, unless --yes.
|
|
57
|
+
|
|
58
|
+
ramdb2-cli infra keygen <server> [--force]
|
|
59
|
+
Creates the SSH key of the server for its backups: secrets/<server>.key, encrypted by sops (.sops.yaml),
|
|
60
|
+
and secrets/<server>.pub, printed, to install on the backup server. --force replaces an existing key.
|
|
61
|
+
|
|
62
|
+
ramdb2-cli infra backups <site>
|
|
63
|
+
The backups of the site, oldest first, listed by its server.
|
|
64
|
+
|
|
65
|
+
ramdb2-cli infra restore <site> [<moment>] [--yes]
|
|
66
|
+
Stops the API and the backups of the site, restores the last backup at or before moment (UTC, e.g.
|
|
67
|
+
2026-11-06T14:00; the most recent by default), checks it, starts them again. Asks first, unless --yes.
|
|
68
|
+
|
|
69
|
+
ramdb2-cli infra fetch <site> <file> [<moment>]
|
|
70
|
+
Writes the backup (the most recent, or the last at or before moment) to a local file, decompressed.
|
|
71
|
+
|
|
38
72
|
ramdb2-cli convert --input <v1 preTypeDefs> --output <v2 preTypeDefs> [--force]
|
|
39
73
|
Converts the v1 annotations ([PERSISTENT], [GROUP=], [FIELD=]) into directives, in a new file.
|
|
40
74
|
`
|
|
41
75
|
|
|
42
76
|
const commands = {
|
|
77
|
+
async infra(values, args) {
|
|
78
|
+
// The infra commands fail with messages for the user: no stack trace
|
|
79
|
+
try {
|
|
80
|
+
await infra(values, args)
|
|
81
|
+
} catch (error) {
|
|
82
|
+
console.error(error.message)
|
|
83
|
+
process.exitCode = 1
|
|
84
|
+
}
|
|
85
|
+
},
|
|
43
86
|
new(values, [dir]) {
|
|
44
87
|
if (dir === undefined) return usage('new needs the folder of the project')
|
|
45
88
|
const withClient = values['with-client'] ?? false
|
|
@@ -84,12 +127,78 @@ const commands = {
|
|
|
84
127
|
},
|
|
85
128
|
}
|
|
86
129
|
|
|
87
|
-
function report({ written, kept, warnings }) {
|
|
130
|
+
function report({ written, kept, removed = [], warnings }) {
|
|
88
131
|
for (const path of written) console.log(`written ${path}`)
|
|
89
132
|
for (const path of kept) console.log(`kept ${path} (written by hand)`)
|
|
133
|
+
for (const path of removed) console.log(`removed ${path} (type no longer in the schema)`)
|
|
90
134
|
for (const warning of warnings) console.log(`warning ${warning}`)
|
|
91
135
|
}
|
|
92
136
|
|
|
137
|
+
async function infra(values, [action, ...args]) {
|
|
138
|
+
const actions = ['build', 'deploy', 'down', 'keygen', 'backups', 'restore', 'fetch']
|
|
139
|
+
if (!actions.includes(action)) return usage(`infra needs an action: ${actions.join(', ')}`)
|
|
140
|
+
const infra = readInfra(values.config ?? 'infra.yaml')
|
|
141
|
+
switch (action) {
|
|
142
|
+
case 'build':
|
|
143
|
+
for (const { server, files } of buildInfra(infra, args)) {
|
|
144
|
+
console.log(`${server}: ${files.length} files`)
|
|
145
|
+
for (const path of files) console.log(`written ${path}`)
|
|
146
|
+
}
|
|
147
|
+
return
|
|
148
|
+
case 'deploy': {
|
|
149
|
+
if (args.length !== 1) return usage('infra deploy needs one server')
|
|
150
|
+
const { certificates } = await deploy(infra, args[0], { staging: values.staging ?? false })
|
|
151
|
+
if (certificates.some(certificate => !certificate.ok)) process.exitCode = 1
|
|
152
|
+
return
|
|
153
|
+
}
|
|
154
|
+
case 'down':
|
|
155
|
+
if (args.length !== 1) return usage('infra down needs one server')
|
|
156
|
+
if (!infra.servers.some(server => server.name === args[0])) throw new Error(`No server ${args[0]} in infra.yaml`)
|
|
157
|
+
if (!values.yes && !(await confirm(`Stop all the sites of ${args[0]}? Their data stays. [y/N] `))) {
|
|
158
|
+
console.log('Nothing done')
|
|
159
|
+
return
|
|
160
|
+
}
|
|
161
|
+
await down(infra, args[0])
|
|
162
|
+
return
|
|
163
|
+
case 'keygen':
|
|
164
|
+
if (args.length !== 1) return usage('infra keygen needs one server')
|
|
165
|
+
await keygen(infra, args[0], { force: values.force ?? false })
|
|
166
|
+
return
|
|
167
|
+
case 'backups':
|
|
168
|
+
if (args.length !== 1) return usage('infra backups needs one site')
|
|
169
|
+
for (const name of await listBackups(infra, args[0])) console.log(name)
|
|
170
|
+
return
|
|
171
|
+
case 'restore': {
|
|
172
|
+
const [site, moment] = args
|
|
173
|
+
if (site === undefined || args.length > 2) return usage('infra restore needs a site, and maybe a moment')
|
|
174
|
+
const what = `the database of ${site} by its backup ${moment === undefined ? 'the most recent' : `at or before ${moment} (UTC)`}`
|
|
175
|
+
if (!values.yes && !(await confirm(`Replace ${what}? The site stops meanwhile. [y/N] `))) {
|
|
176
|
+
console.log('Nothing done')
|
|
177
|
+
return
|
|
178
|
+
}
|
|
179
|
+
await restore(infra, site, { moment })
|
|
180
|
+
return
|
|
181
|
+
}
|
|
182
|
+
case 'fetch': {
|
|
183
|
+
const [site, file, moment] = args
|
|
184
|
+
if (site === undefined || file === undefined || args.length > 3) return usage('infra fetch needs a site and a file')
|
|
185
|
+
await fetchBackup(infra, site, file, { moment })
|
|
186
|
+
console.log(`written ${file}`)
|
|
187
|
+
return
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
async function confirm(question) {
|
|
193
|
+
if (!process.stdin.isTTY) throw new Error('Not a terminal: add --yes to confirm')
|
|
194
|
+
const terminal = createInterface({ input: process.stdin, output: process.stdout })
|
|
195
|
+
try {
|
|
196
|
+
return /^(y|yes|o|oui)$/i.test((await terminal.question(question)).trim())
|
|
197
|
+
} finally {
|
|
198
|
+
terminal.close()
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
93
202
|
function usage(message) {
|
|
94
203
|
console.error(`${message}\n\n${HELP}`)
|
|
95
204
|
process.exitCode = 1
|
|
@@ -107,6 +216,9 @@ const { values, positionals } = parseArgs({
|
|
|
107
216
|
'with-client': { type: 'boolean' },
|
|
108
217
|
variables: { type: 'string' },
|
|
109
218
|
file: { type: 'string' },
|
|
219
|
+
config: { type: 'string' },
|
|
220
|
+
staging: { type: 'boolean' },
|
|
221
|
+
yes: { type: 'boolean', short: 'y' },
|
|
110
222
|
help: { type: 'boolean', short: 'h' },
|
|
111
223
|
},
|
|
112
224
|
})
|
|
@@ -118,7 +230,7 @@ if (values.help || command === undefined) {
|
|
|
118
230
|
try {
|
|
119
231
|
await command(values, positionals.slice(1))
|
|
120
232
|
} catch (error) {
|
|
121
|
-
console.error(error.name
|
|
233
|
+
console.error(['SchemaError', 'InfraError'].includes(error.name) || error.message.startsWith('No profile') ? error.message : error)
|
|
122
234
|
process.exitCode = 1
|
|
123
235
|
}
|
|
124
236
|
}
|
package/src/directives.js
CHANGED
|
@@ -27,16 +27,19 @@ directive @computed(depends: [String!]!) on FIELD_DEFINITION
|
|
|
27
27
|
"Validation rule: the value must match the regular expression."
|
|
28
28
|
directive @pattern(regex: String!, message: String) on FIELD_DEFINITION
|
|
29
29
|
|
|
30
|
-
"Field of a persistent type that is not stored: resolved elsewhere."
|
|
31
|
-
directive @transient on FIELD_DEFINITION
|
|
30
|
+
"Field of a persistent type that is not stored: resolved elsewhere. getter: a getter of the class gives its value, so a query can filter and sort on it (D62)."
|
|
31
|
+
directive @transient(getter: Boolean = false) on FIELD_DEFINITION
|
|
32
32
|
|
|
33
33
|
"Field stored and readable in code, but absent from the GraphQL API: neither read, written nor queried (D47)."
|
|
34
34
|
directive @private on FIELD_DEFINITION
|
|
35
35
|
|
|
36
|
+
"Field readable only when the permission of the server allows it, for each object (D58): served nullable."
|
|
37
|
+
directive @restricted on FIELD_DEFINITION
|
|
38
|
+
|
|
36
39
|
"Value masked in the logs. Kept in the schema served by Apollo: ramdb2-server reads it."
|
|
37
40
|
directive @sensitive on FIELD_DEFINITION | INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
|
|
38
41
|
`
|
|
39
42
|
|
|
40
43
|
/** Names of the directives above removed from the schema served by Apollo: all but @sensitive. */
|
|
41
|
-
export const DIRECTIVE_NAMES = new Set(['persistent', 'group', 'index', 'field', 'onDelete', 'computed', 'pattern', 'transient', 'private'])
|
|
44
|
+
export const DIRECTIVE_NAMES = new Set(['persistent', 'group', 'index', 'field', 'onDelete', 'computed', 'pattern', 'transient', 'private', 'restricted'])
|
|
42
45
|
export const INTERNAL_TYPES = new Set(['RamdbIndexType', 'RamdbOnDelete'])
|
package/src/generate/classes.js
CHANGED
|
@@ -40,6 +40,24 @@ function generatedClass(type, model, code) {
|
|
|
40
40
|
lines.push(' // @private: never read, written nor queried through the GraphQL API')
|
|
41
41
|
lines.push(` static privateFields = [${privateFields.map(quote).join(', ')}]`)
|
|
42
42
|
}
|
|
43
|
+
if (type.restricted.length > 0) {
|
|
44
|
+
lines.push('')
|
|
45
|
+
lines.push(' // @restricted: read through the API only when permissions.<Type>.fields allows it (D58)')
|
|
46
|
+
lines.push(` static restrictedFields = [${type.restricted.map(quote).join(', ')}]`)
|
|
47
|
+
}
|
|
48
|
+
if (type.transient.length > 0) {
|
|
49
|
+
lines.push('')
|
|
50
|
+
lines.push(' // @transient: not stored. Those of transientGetters are getters of the class, filtered and sorted by a query (D62)')
|
|
51
|
+
lines.push(` static transient = [${type.transient.map(t => quote(t.name)).join(', ')}]`)
|
|
52
|
+
lines.push(` static transientGetters = [${type.transient.filter(t => t.getter).map(t => quote(t.name)).join(', ')}]`)
|
|
53
|
+
}
|
|
54
|
+
if (type.children.length > 0) {
|
|
55
|
+
lines.push('')
|
|
56
|
+
lines.push(' // The list relations: the table of their objects and the foreign key that points here')
|
|
57
|
+
lines.push(' static listRelations = {')
|
|
58
|
+
for (const child of type.children) lines.push(` ${child.name}: { table: '${byNameTable(model, child.target)}', key: '${child.fk}' },`)
|
|
59
|
+
lines.push(' }')
|
|
60
|
+
}
|
|
43
61
|
|
|
44
62
|
const foreignKeys = type.parents.map(parent => [parent, onDeleteOf(parent, type, model)])
|
|
45
63
|
if (foreignKeys.length > 0) {
|
|
@@ -259,6 +277,13 @@ function extendedClass(type) {
|
|
|
259
277
|
lines.push('')
|
|
260
278
|
lines.push(' // Integrity rules checked by delete(): (values, obj) => "" | message')
|
|
261
279
|
lines.push(' static deleteRules = []')
|
|
280
|
+
for (const transient of type.transient.filter(t => t.getter)) {
|
|
281
|
+
lines.push('')
|
|
282
|
+
lines.push(` /** @returns {${transient.jsType}} @transient(getter: true): read by GraphQL and by the queries (D62) */`)
|
|
283
|
+
lines.push(` get ${transient.name}() {`)
|
|
284
|
+
lines.push(` throw new Error('${type.name}.${transient.name} is not written yet')`)
|
|
285
|
+
lines.push(' }')
|
|
286
|
+
}
|
|
262
287
|
for (const computed of type.computed) {
|
|
263
288
|
lines.push('')
|
|
264
289
|
lines.push(` /** @returns {${computed.jsType}} depends on ${computed.depends.join(', ')} */`)
|
|
@@ -290,3 +315,7 @@ export function jsdoc(description, indent, extra = []) {
|
|
|
290
315
|
export function quote(string) {
|
|
291
316
|
return `'${string}'`
|
|
292
317
|
}
|
|
318
|
+
|
|
319
|
+
function byNameTable(model, name) {
|
|
320
|
+
return model.byName.get(name).table
|
|
321
|
+
}
|
package/src/generate/client.js
CHANGED
|
@@ -70,6 +70,9 @@ function generatedClass(type, model) {
|
|
|
70
70
|
lines.push('')
|
|
71
71
|
lines.push(` static transient = [${transient.map(t => quote(t.name)).join(', ')}]`)
|
|
72
72
|
lines.push('')
|
|
73
|
+
lines.push(' // Getters of the server class: filtered and sorted by a query (D62 of ramdb2)')
|
|
74
|
+
lines.push(` static transientGetters = [${transient.filter(t => t.getter).map(t => quote(t.name)).join(', ')}]`)
|
|
75
|
+
lines.push('')
|
|
73
76
|
lines.push(` static fullText = [${fullText.map(quote).join(', ')}]`)
|
|
74
77
|
lines.push('')
|
|
75
78
|
const relations = [
|
|
@@ -89,34 +92,39 @@ function generatedClass(type, model) {
|
|
|
89
92
|
lines.push(' }')
|
|
90
93
|
}
|
|
91
94
|
|
|
95
|
+
// A @restricted field may be hidden by its permission on the server (D58): null
|
|
96
|
+
const orNull = (name, jsType) => type.restricted.includes(name) && !/\bnull\b/.test(jsType) ? `${jsType} | null` : jsType
|
|
92
97
|
for (const parent of type.parents) {
|
|
93
98
|
lines.push('')
|
|
94
|
-
lines.push(` /** @returns {number} foreign key of ${parent.name}, 0 = none */`)
|
|
99
|
+
lines.push(` /** @returns {${orNull(parent.fk, 'number')}} foreign key of ${parent.name}, 0 = none */`)
|
|
95
100
|
lines.push(` get ${parent.fk}() { return this._f.${parent.fk} }`)
|
|
96
101
|
}
|
|
97
102
|
for (const field of fields) {
|
|
98
103
|
lines.push('')
|
|
99
|
-
lines.push(jsdoc(field.description, ' ', [`@returns {${field.jsType}}`]))
|
|
104
|
+
lines.push(jsdoc(field.description, ' ', [`@returns {${orNull(field.name, field.jsType)}}`]))
|
|
100
105
|
lines.push(` get ${field.name}() { return this._f.${field.name} }`)
|
|
101
106
|
}
|
|
102
107
|
for (const relation of [...type.parents, ...type.children]) {
|
|
103
108
|
const target = model.byName.get(relation.target)
|
|
104
|
-
|
|
109
|
+
// An object relation may be hidden by the permission see of the server (D57): null
|
|
110
|
+
const returns = type.children.includes(relation) ? '[]' : ' | null'
|
|
105
111
|
lines.push('')
|
|
106
112
|
lines.push(jsdoc(relation.description, ' ', [
|
|
107
113
|
`Loaded with include: ['${relation.name}'].`,
|
|
108
|
-
`@returns {import('../extended/${target.table}.js').default${
|
|
114
|
+
`@returns {import('../extended/${target.table}.js').default${returns}}`,
|
|
109
115
|
]))
|
|
110
116
|
lines.push(` get ${relation.name}() { return this._relation('${relation.name}') }`)
|
|
111
117
|
}
|
|
112
118
|
for (const computed of type.computed) {
|
|
113
119
|
lines.push('')
|
|
114
|
-
|
|
120
|
+
// Served nullable when it leads to one persistent object (D57)
|
|
121
|
+
const served = /^\w+!$/.test(computed.display) && model.byName.has(computed.display.slice(0, -1)) ? `${computed.jsType} | null` : computed.jsType
|
|
122
|
+
lines.push(jsdoc(computed.description, ' ', ['Computed by the server.', `@returns {${orNull(computed.name, served)}}`]))
|
|
115
123
|
lines.push(` get ${computed.name}() { return this._c.${computed.name} }`)
|
|
116
124
|
}
|
|
117
125
|
for (const field of transient) {
|
|
118
126
|
lines.push('')
|
|
119
|
-
lines.push(jsdoc(field.description, ' ', ['Resolved by the project on the server.', `@returns {${field.jsType}}`]))
|
|
127
|
+
lines.push(jsdoc(field.description, ' ', ['Resolved by the project on the server.', `@returns {${orNull(field.name, field.jsType)}}`]))
|
|
120
128
|
lines.push(` get ${field.name}() { return this._c.${field.name} }`)
|
|
121
129
|
}
|
|
122
130
|
lines.push('}')
|
package/src/generate/typeDefs.js
CHANGED
|
@@ -3,6 +3,8 @@ import { DIRECTIVE_NAMES } from '../directives.js'
|
|
|
3
3
|
|
|
4
4
|
// The schema served by Apollo (spec section 3): the preTypeDefs without the directives of ramdb2-cli,
|
|
5
5
|
// descriptions kept, with the id and the foreign keys of the persistent types.
|
|
6
|
+
// A field that leads to one persistent object is served nullable (D57): the permission `see` may hide it.
|
|
7
|
+
// A @restricted field, and the foreign key of a @restricted relation, too (D58): its permission may hide it.
|
|
6
8
|
|
|
7
9
|
/**
|
|
8
10
|
* @param {import('../model.js').Model} model
|
|
@@ -23,8 +25,9 @@ export function typeDefsFile(model) {
|
|
|
23
25
|
if (field.directives?.some(directive => directive.name.value === 'private')) continue
|
|
24
26
|
const parent = type.parents.find(p => p.name === field.name.value)
|
|
25
27
|
// The foreign key, before its relation: what a client sends to create or modify the object
|
|
26
|
-
|
|
27
|
-
fields.push(
|
|
28
|
+
const restricted = type.restricted.includes(field.name.value)
|
|
29
|
+
if (parent !== undefined) fields.push(fieldNode(`${parent.fk}: Int${restricted ? '' : '!'}`))
|
|
30
|
+
fields.push(restricted ? nullable(field) : nullableObject(field, model))
|
|
28
31
|
}
|
|
29
32
|
return { ...node, fields }
|
|
30
33
|
},
|
|
@@ -33,6 +36,17 @@ export function typeDefsFile(model) {
|
|
|
33
36
|
return { path: 'schema/typeDefs.graphql', content: header + print(document) + '\n', overwrite: true }
|
|
34
37
|
}
|
|
35
38
|
|
|
39
|
+
// `project: Project!` → `project: Project`: the ! keeps its meaning of required foreign key in the model only
|
|
40
|
+
function nullableObject(field, model) {
|
|
41
|
+
const type = field.type
|
|
42
|
+
if (type.kind !== Kind.NON_NULL_TYPE || type.type.kind !== Kind.NAMED_TYPE || !model.byName.has(type.type.name.value)) return field
|
|
43
|
+
return { ...field, type: type.type }
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function nullable(field) {
|
|
47
|
+
return field.type.kind === Kind.NON_NULL_TYPE ? { ...field, type: field.type.type } : field
|
|
48
|
+
}
|
|
49
|
+
|
|
36
50
|
function fieldNode(source) {
|
|
37
51
|
const field = parse(`type T { ${source} }`, { noLocation: true }).definitions[0].fields[0]
|
|
38
52
|
return field.kind === Kind.FIELD_DEFINITION ? field : undefined
|