ramdb2-cli 2.0.0-alpha.1 → 2.0.0-alpha.11

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 CHANGED
@@ -1,5 +1,59 @@
1
1
  # ramdb2-cli
2
2
 
3
+ ## 2.0.0-alpha.11
4
+
5
+ ### Patch Changes
6
+
7
+ - cf18bd4: Dates stored as Unix seconds (D64 of ramdb2, D25 of the client). The directives `@date` (a day, without time zone: the seconds of its midnight UTC) and `@datetime` (an instant) go on an `Int` field; 0 or null is no date. The generated client class lists them in `static dates`. `ramdb2-core` and `ramdb2-client` export the same date functions: `day`, `dayText`, `dateTime`, `dateTimeText`, `today(timeZone)`, `dayOf`, `addDays`, `addMonths`… ramdb2-vue shows them as `YYYY-MM-DD` (`HH:MM:SS`), sorts and filters on the seconds, searches a typed day, month or year, exports real Excel dates and CSV text, and types them with the date input of the browser; option `dates: { timeZone, formatDate, formatDateTime }` of the site. The schema of `ramdb2-cli new` gets `Task.due: Int @date`.
8
+
9
+ ## 2.0.0-alpha.10
10
+
11
+ No changes in this release.
12
+
13
+ ## 2.0.0-alpha.9
14
+
15
+ No changes in this release.
16
+
17
+ ## 2.0.0-alpha.8
18
+
19
+ No changes in this release.
20
+
21
+ ## 2.0.0-alpha.7
22
+
23
+ ### Minor Changes
24
+
25
+ - 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).
26
+
27
+ ## 2.0.0-alpha.6
28
+
29
+ No changes in this release.
30
+
31
+ ## 2.0.0-alpha.5
32
+
33
+ ### Minor Changes
34
+
35
+ - e34f3bd: `generate` and `client` remove the generated classes of a type gone from the schema, and name its extended class in a warning (D61).
36
+
37
+ ## 2.0.0-alpha.4
38
+
39
+ ### Minor Changes
40
+
41
+ - 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.
42
+ - 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`.
43
+
44
+ ## 2.0.0-alpha.3
45
+
46
+ ### Minor Changes
47
+
48
+ - 92570bd: `ramdb2-cli infra down <server>`: stops a server (docker compose down), keeps its volumes; asks first, unless `--yes`.
49
+
50
+ ## 2.0.0-alpha.2
51
+
52
+ ### Minor Changes
53
+
54
+ - 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.
55
+ - 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.
56
+
3
57
  ## 2.0.0-alpha.1
4
58
 
5
59
  ### Minor Changes
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,12 @@ 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
+ | `@date` | field | | an `Int` that is a day of the calendar, without time zone: the Unix seconds of its midnight UTC; 0 or null for no date. ramdb2-vue shows, searches, exports and types it as a date |
107
+ | `@datetime` | field | | an `Int` that is an instant: Unix seconds; 0 or null for no date. Shown and typed in the time zone of the site |
108
+ | `@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
109
 
103
110
  ### How the fields are read
104
111
 
@@ -258,6 +265,7 @@ as for `generate`). It writes, in `--dest`:
258
265
  API.
259
266
  - `transient`: the `@transient` fields of a scalar type (scalar, enum, custom scalar, list of them), always loaded
260
267
  with the object. One of an object type, or with a required argument, is left out with a warning.
268
+ - `transientGetters`: the `@transient(getter: true)` fields, sorted by default in a `RdbCrud`.
261
269
  - `fullText`: the fields of the `FULLTEXT` index, in the order of the schema (`[]` without one), for a search with `$text`.
262
270
  - `generatedRules`: the same rules as the server (`required`, `pattern`, `oneOf`), plus `requiredKey('idProject')`
263
271
  for a required object relation.
@@ -414,6 +422,126 @@ All the errors of `infra.yaml` are reported at once. `build/<server>/` holds:
414
422
  - The healthcheck of the API sends the GraphQL query `health`: keep it open without a login.
415
423
  - Until a certificate exists, nginx serves a self-signed one, so that it can start.
416
424
 
425
+ ### Deploy
426
+
427
+ ```sh
428
+ ramdb2-cli infra deploy ovh1 # build, then up on the server, then the certificates
429
+ ramdb2-cli infra deploy ovh1 --staging # with the test certificates of Let's Encrypt
430
+ ```
431
+
432
+ The secrets live in the infra folder, encrypted by [sops](https://github.com/getsops/sops) (with
433
+ [age](https://github.com/FiloSottile/age) keys listed in `.sops.yaml`):
434
+
435
+ | File | Content |
436
+ |---|---|
437
+ | `secrets/<site>.env` | the environment of the API of a site (`TOKEN_SECRET`…) |
438
+ | `secrets/<server>.key` | the private SSH key of the server, for its backups |
439
+
440
+ `deploy` needs `docker`, `sops` and an SSH access to the server on your machine. It:
441
+
442
+ 1. runs `build` for the server;
443
+ 2. decrypts the secrets into a private temporary folder, deleted at the end;
444
+ 3. runs `docker compose up -d --build --remove-orphans` with `DOCKER_HOST` set to the `host` of the server: the
445
+ images are built on the server;
446
+ 4. asks Let's Encrypt for each certificate (nothing is done while a certificate is valid; it is made again when
447
+ its domains change), then reloads nginx.
448
+
449
+ It stops before Docker when a secret is missing or cannot be decrypted. A refused certificate (a domain that does
450
+ not point to the server yet) does not stop the others; the exit code is then 1.
451
+
452
+ The decrypted secrets live in `build/<server>/.secrets-*` (only you can read it) while a command runs, and are
453
+ deleted at the end, even on an error. Not in `/tmp`: Docker installed as a snap cannot read it.
454
+
455
+ ### Stop a server
456
+
457
+ ```sh
458
+ ramdb2-cli infra down ovh1 # asks first; --yes to skip the question
459
+ ```
460
+
461
+ `down` runs `docker compose down --remove-orphans` on the server: the containers of all its sites (ramdb2 and
462
+ custom) and its network are removed. The volumes (the databases, the backup queues), the images and the
463
+ certificates stay: `ramdb2-cli infra deploy ovh1` starts the server again as it was. Like every command that talks
464
+ to a server, it decrypts the secrets: Compose needs them to read `compose.yaml`.
465
+
466
+ ### Secrets: sops and age, once
467
+
468
+ ```sh
469
+ age-keygen -o ~/.config/sops/age/keys.txt # your age key, where sops looks for it
470
+ age-keygen -y ~/.config/sops/age/keys.txt # its public key, for .sops.yaml
471
+ ```
472
+
473
+ `.sops.yaml`, at the root of the infra folder:
474
+
475
+ ```yaml
476
+ creation_rules:
477
+ - path_regex: secrets/.*
478
+ age: age1...your public key...
479
+ ```
480
+
481
+ Keep a copy of your age key somewhere safe (a password manager): without it, no secret can be decrypted, and no
482
+ server can be deployed. Then the secrets of a site:
483
+
484
+ ```sh
485
+ sops secrets/ilife.env # opens your editor; saved encrypted. TOKEN_SECRET=..., one variable per line
486
+ ```
487
+
488
+ ### The backup key of a server
489
+
490
+ ```sh
491
+ ramdb2-cli infra keygen ovh1
492
+ ```
493
+
494
+ Creates an SSH key for the backups of the server: `secrets/ovh1.key`, encrypted by sops, and `secrets/ovh1.pub`.
495
+ It prints the line to add to `~backup/.ssh/authorized_keys` on the backup server:
496
+ `restrict ssh-ed25519 AAAA... ramdb2-backup-ovh1`. An existing key is replaced only with `--force`; install the
497
+ new public key then, and deploy again.
498
+
499
+ ### The backup server
500
+
501
+ Any OpenSSH server. A user `backup`, which can only use SFTP, locked in the backup folder, with keys only. In
502
+ `/etc/ssh/sshd_config`:
503
+
504
+ ```
505
+ PasswordAuthentication no
506
+ KbdInteractiveAuthentication no
507
+ Subsystem sftp internal-sftp
508
+
509
+ Match User backup
510
+ ChrootDirectory /volume1/backup
511
+ ForceCommand internal-sftp
512
+ AllowTcpForwarding no
513
+ X11Forwarding no
514
+ ```
515
+
516
+ - The chroot folder (`/volume1/backup`) belongs to root and only root can write it (an OpenSSH rule); the folder
517
+ of the backups inside it (`ramdb2`) belongs to `backup`.
518
+ - `backup.target` in `infra.yaml` is then `sftp://backup@host:22/ramdb2`: the path is seen from the chroot.
519
+ - Each server key sees the backups of every site: a site can move to another server and keep its backups.
520
+ - The first connection of a server accepts the host key of the backup server, then checks it.
521
+
522
+ ### Backups and restore
523
+
524
+ Each ramdb2 site has its backup container: a compressed image of the database every 5 minutes, sent to the
525
+ backup server, then pruned there (every backup of the last 24 hours, the last of each day for 30 days, the last of
526
+ each month forever). See [`ramdb2-server-backup`](https://www.npmjs.com/package/ramdb2-server). From your machine:
527
+
528
+ ```sh
529
+ ramdb2-cli infra backups ilife # the backups of the site, oldest first
530
+ ramdb2-cli infra restore ilife # the most recent backup
531
+ ramdb2-cli infra restore ilife 2026-11-06T14:00 # the last one at or before that moment (UTC)
532
+ ramdb2-cli infra fetch ilife ilife.db # the most recent backup, to a local file
533
+ ramdb2-cli infra fetch ilife ilife.db 2026-11-06T14:00
534
+ ```
535
+
536
+ - The server of a site is read in `infra.yaml`. The commands run on it, in the backup container of the site, with
537
+ the key of the server: your machine needs no access to the backup server.
538
+ - `restore` asks first (`--yes` to skip the question). It stops the API and the backups of the site, checks the
539
+ backup (`PRAGMA integrity_check`), replaces the database, then starts them again; when the backup is damaged,
540
+ the database is left as it was and the site starts again.
541
+ - A new server: install Docker, `ramdb2-cli infra deploy <server>`, then `ramdb2-cli infra restore <site>` for each
542
+ site.
543
+ - `fetch` writes a database you can open with any SQLite tool, or use as `DB_PATH` of the project on your machine.
544
+
417
545
  ---
418
546
 
419
547
  ## Programmatic use
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ramdb2-cli",
3
- "version": "2.0.0-alpha.1",
3
+ "version": "2.0.0-alpha.11",
4
4
  "description": "Code generator and project scaffolding for ramdb2 and ramdb2-server",
5
5
  "type": "module",
6
6
  "exports": "./src/index.js",
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "devDependencies": {
30
30
  "@vitejs/plugin-vue": "^6.0.10",
31
- "ramdb2-core": "^2.0.0-alpha.1",
31
+ "ramdb2-core": "^2.0.0-alpha.11",
32
32
  "vite": "^8.3.5",
33
33
  "vue": "^3.5.44",
34
34
  "vue-router": "^5.4.0"
package/src/cli.js CHANGED
@@ -8,6 +8,11 @@ import { plantuml } from './plantuml.js'
8
8
  import { query } from './query.js'
9
9
  import { readInfra } from './infra/config.js'
10
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'
11
16
 
12
17
  const HELP = `ramdb2-cli: code generator of ramdb2
13
18
 
@@ -41,17 +46,41 @@ const HELP = `ramdb2-cli: code generator of ramdb2
41
46
  Writes build/<server>/ next to infra.yaml (all the servers by default): compose.yaml, the front nginx,
42
47
  the Dockerfiles of each site. Generated, rewritten each time: keep build/ out of git.
43
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
+
44
72
  ramdb2-cli convert --input <v1 preTypeDefs> --output <v2 preTypeDefs> [--force]
45
73
  Converts the v1 annotations ([PERSISTENT], [GROUP=], [FIELD=]) into directives, in a new file.
46
74
  `
47
75
 
48
76
  const commands = {
49
- infra(values, [action, ...servers]) {
50
- if (action !== 'build') return usage('infra needs an action: build')
51
- const infra = readInfra(values.config ?? 'infra.yaml')
52
- for (const { server, files } of buildInfra(infra, servers)) {
53
- console.log(`${server}: ${files.length} files`)
54
- for (const path of files) console.log(`written ${path}`)
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
55
84
  }
56
85
  },
57
86
  new(values, [dir]) {
@@ -98,12 +127,78 @@ const commands = {
98
127
  },
99
128
  }
100
129
 
101
- function report({ written, kept, warnings }) {
130
+ function report({ written, kept, removed = [], warnings }) {
102
131
  for (const path of written) console.log(`written ${path}`)
103
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)`)
104
134
  for (const warning of warnings) console.log(`warning ${warning}`)
105
135
  }
106
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
+
107
202
  function usage(message) {
108
203
  console.error(`${message}\n\n${HELP}`)
109
204
  process.exitCode = 1
@@ -122,6 +217,8 @@ const { values, positionals } = parseArgs({
122
217
  variables: { type: 'string' },
123
218
  file: { type: 'string' },
124
219
  config: { type: 'string' },
220
+ staging: { type: 'boolean' },
221
+ yes: { type: 'boolean', short: 'y' },
125
222
  help: { type: 'boolean', short: 'h' },
126
223
  },
127
224
  })
@@ -133,7 +230,7 @@ if (values.help || command === undefined) {
133
230
  try {
134
231
  await command(values, positionals.slice(1))
135
232
  } catch (error) {
136
- console.error(['SchemaError', 'InfraError'].includes(error.name) || error.message.startsWith('No profile') ? error.message : error)
233
+ console.error(['SchemaError', 'InfraError'].includes(error.name) || error.message.startsWith('No profile') ? error.message : error)
137
234
  process.exitCode = 1
138
235
  }
139
236
  }
package/src/directives.js CHANGED
@@ -27,16 +27,25 @@ 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
+
39
+ "An Int that is a day of the calendar, without time zone: the Unix seconds of its midnight UTC; 0 or null for no date (D64). Shown, searched, exported and typed as a date by ramdb2-vue."
40
+ directive @date on FIELD_DEFINITION
41
+
42
+ "An Int that is an instant: Unix seconds; 0 or null for no date (D64). Shown, searched, exported and typed as a date and a time by ramdb2-vue."
43
+ directive @datetime on FIELD_DEFINITION
44
+
36
45
  "Value masked in the logs. Kept in the schema served by Apollo: ramdb2-server reads it."
37
46
  directive @sensitive on FIELD_DEFINITION | INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
38
47
  `
39
48
 
40
49
  /** 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'])
50
+ export const DIRECTIVE_NAMES = new Set(['persistent', 'group', 'index', 'field', 'onDelete', 'computed', 'pattern', 'transient', 'private', 'restricted', 'date', 'datetime'])
42
51
  export const INTERNAL_TYPES = new Set(['RamdbIndexType', 'RamdbOnDelete'])
@@ -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
+ }
@@ -70,8 +70,15 @@ 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('')
78
+ // The Int fields that are dates, in Unix seconds (D64 of ramdb2): a day (date) or an instant (datetime)
79
+ const dates = Object.entries(type.dates).filter(([name]) => !privateFields.includes(name))
80
+ lines.push(` static dates = {${dates.length ? ' ' + dates.map(([name, kind]) => `${name}: '${kind}'`).join(', ') + ' ' : ''}}`)
81
+ lines.push('')
75
82
  const relations = [
76
83
  ...type.parents.map(p => ` ${p.name}: { type: '${p.target}', key: '${p.fk}' },`),
77
84
  ...type.children.map(c => ` ${c.name}: { type: '${c.target}', key: '${c.fk}', list: true },`),
@@ -89,34 +96,39 @@ function generatedClass(type, model) {
89
96
  lines.push(' }')
90
97
  }
91
98
 
99
+ // A @restricted field may be hidden by its permission on the server (D58): null
100
+ const orNull = (name, jsType) => type.restricted.includes(name) && !/\bnull\b/.test(jsType) ? `${jsType} | null` : jsType
92
101
  for (const parent of type.parents) {
93
102
  lines.push('')
94
- lines.push(` /** @returns {number} foreign key of ${parent.name}, 0 = none */`)
103
+ lines.push(` /** @returns {${orNull(parent.fk, 'number')}} foreign key of ${parent.name}, 0 = none */`)
95
104
  lines.push(` get ${parent.fk}() { return this._f.${parent.fk} }`)
96
105
  }
97
106
  for (const field of fields) {
98
107
  lines.push('')
99
- lines.push(jsdoc(field.description, ' ', [`@returns {${field.jsType}}`]))
108
+ lines.push(jsdoc(field.description, ' ', [`@returns {${orNull(field.name, field.jsType)}}`]))
100
109
  lines.push(` get ${field.name}() { return this._f.${field.name} }`)
101
110
  }
102
111
  for (const relation of [...type.parents, ...type.children]) {
103
112
  const target = model.byName.get(relation.target)
104
- const list = type.children.includes(relation) ? '[]' : ''
113
+ // An object relation may be hidden by the permission see of the server (D57): null
114
+ const returns = type.children.includes(relation) ? '[]' : ' | null'
105
115
  lines.push('')
106
116
  lines.push(jsdoc(relation.description, ' ', [
107
117
  `Loaded with include: ['${relation.name}'].`,
108
- `@returns {import('../extended/${target.table}.js').default${list}}`,
118
+ `@returns {import('../extended/${target.table}.js').default${returns}}`,
109
119
  ]))
110
120
  lines.push(` get ${relation.name}() { return this._relation('${relation.name}') }`)
111
121
  }
112
122
  for (const computed of type.computed) {
113
123
  lines.push('')
114
- lines.push(jsdoc(computed.description, ' ', ['Computed by the server.', `@returns {${computed.jsType}}`]))
124
+ // Served nullable when it leads to one persistent object (D57)
125
+ const served = /^\w+!$/.test(computed.display) && model.byName.has(computed.display.slice(0, -1)) ? `${computed.jsType} | null` : computed.jsType
126
+ lines.push(jsdoc(computed.description, ' ', ['Computed by the server.', `@returns {${orNull(computed.name, served)}}`]))
115
127
  lines.push(` get ${computed.name}() { return this._c.${computed.name} }`)
116
128
  }
117
129
  for (const field of transient) {
118
130
  lines.push('')
119
- lines.push(jsdoc(field.description, ' ', ['Resolved by the project on the server.', `@returns {${field.jsType}}`]))
131
+ lines.push(jsdoc(field.description, ' ', ['Resolved by the project on the server.', `@returns {${orNull(field.name, field.jsType)}}`]))
120
132
  lines.push(` get ${field.name}() { return this._c.${field.name} }`)
121
133
  }
122
134
  lines.push('}')
@@ -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
- if (parent !== undefined) fields.push(fieldNode(`${parent.fk}: Int!`))
27
- fields.push(field)
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
package/src/generate.js CHANGED
@@ -1,5 +1,5 @@
1
- import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
2
- import { dirname, join } from 'node:path'
1
+ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
2
+ import { dirname, join, posix } from 'node:path'
3
3
  import { readSchema } from './model.js'
4
4
  import { classFiles } from './generate/classes.js'
5
5
  import { clientFiles } from './generate/client.js'
@@ -9,24 +9,29 @@ import { operationsFile } from './generate/operations.js'
9
9
  /**
10
10
  * Generates the database layer of a project from its preTypeDefs (spec section 12).
11
11
  * Generated files are rewritten; files written by hand (extended classes) are created only when missing.
12
+ * The generated classes of a type gone from the schema are removed, its extended class is named in a warning.
12
13
  * @param {{schema: string | string[], dest: string}} options schema file(s), destination folder
13
- * @returns {{written: string[], kept: string[], warnings: string[]}} paths relative to dest
14
+ * @returns {{written: string[], kept: string[], removed: string[], warnings: string[]}} paths relative to dest
14
15
  */
15
16
  export function generate({ schema, dest }) {
16
17
  const model = readSchemaFiles(schema)
17
- return { ...writeFiles([...classFiles(model), typeDefsFile(model), operationsFile(model)], dest), warnings: model.warnings }
18
+ const files = [...classFiles(model), typeDefsFile(model), operationsFile(model)]
19
+ const { removed, warnings } = removeOrphans(files, dest)
20
+ return { ...writeFiles(files, dest), removed, warnings: [...model.warnings, ...warnings] }
18
21
  }
19
22
 
20
23
  /**
21
24
  * Generates the classes of a ramdb2-client application from the preTypeDefs of its server (spec section 12, D49):
22
- * generated/<table>.js (rewritten), extended/<table>.js (created once) and index.js, in dest.
25
+ * generated/<table>.js (rewritten), extended/<table>.js (created once) and index.js, in dest. Orphans are handled
26
+ * as by generate.
23
27
  * @param {{schema: string | string[], dest: string}} options schema file(s), destination folder
24
- * @returns {{written: string[], kept: string[], warnings: string[]}} paths relative to dest
28
+ * @returns {{written: string[], kept: string[], removed: string[], warnings: string[]}} paths relative to dest
25
29
  */
26
30
  export function generateClient({ schema, dest }) {
27
31
  const model = readSchemaFiles(schema)
28
32
  const { files, warnings } = clientFiles(model)
29
- return { ...writeFiles(files, dest), warnings: [...model.warnings, ...warnings] }
33
+ const orphans = removeOrphans(files, dest)
34
+ return { ...writeFiles(files, dest), removed: orphans.removed, warnings: [...model.warnings, ...warnings, ...orphans.warnings] }
30
35
  }
31
36
 
32
37
  function readSchemaFiles(schema) {
@@ -49,3 +54,36 @@ function writeFiles(files, dest) {
49
54
  }
50
55
  return { written, kept }
51
56
  }
57
+
58
+ // The marker of a file written by ramdb2-cli: only such a file is ever removed
59
+ const GENERATED = '// Generated by ramdb2-cli'
60
+
61
+ // The classes of a type removed from the schema (D61): in each folder of generated classes, a generated file that
62
+ // this generation does not write is removed; in each folder of extended classes, a file without its generated
63
+ // class is only named in a warning, since it was written by hand.
64
+ function removeOrphans(files, dest) {
65
+ const removed = []
66
+ const warnings = []
67
+ const folders = new Map()
68
+ for (const file of files) {
69
+ const folder = posix.dirname(file.path)
70
+ if (!['generated', 'extended'].includes(posix.basename(folder))) continue
71
+ if (!folders.has(folder)) folders.set(folder, new Set())
72
+ folders.get(folder).add(posix.basename(file.path))
73
+ }
74
+ for (const [folder, names] of folders) {
75
+ const path = join(dest, folder)
76
+ if (!existsSync(path)) continue
77
+ for (const entry of readdirSync(path, { withFileTypes: true })) {
78
+ if (!entry.isFile() || !entry.name.endsWith('.js') || names.has(entry.name)) continue
79
+ const relative = posix.join(folder, entry.name)
80
+ if (posix.basename(folder) === 'extended') {
81
+ warnings.push(`${relative}: its type is no longer in the schema, remove it by hand if it is not used`)
82
+ } else if (readFileSync(join(path, entry.name), 'utf8').startsWith(GENERATED)) {
83
+ rmSync(join(path, entry.name))
84
+ removed.push(relative)
85
+ }
86
+ }
87
+ }
88
+ return { removed, warnings }
89
+ }
package/src/index.js CHANGED
@@ -8,3 +8,7 @@ export { DIRECTIVES } from './directives.js'
8
8
  export { operationNames } from './generate/operations.js'
9
9
  export { readInfra, InfraError } from './infra/config.js'
10
10
  export { buildInfra, serverFiles, certificates } from './infra/build.js'
11
+ export { deploy } from './infra/deploy.js'
12
+ export { down } from './infra/down.js'
13
+ export { keygen } from './infra/keygen.js'
14
+ export { listBackups, restore, fetch as fetchBackup } from './infra/backups.js'
@@ -0,0 +1,77 @@
1
+ // ramdb2-cli infra backups, restore and fetch (D56), from the deployment machine: ramdb2-server-backup run in the
2
+ // backup container of the site, on its server (DOCKER_HOST), with the key of the server. The deployment machine
3
+ // needs no access to the backup server.
4
+ import { renameSync, rmSync } from 'node:fs'
5
+ import { check, runCommand, serverOf, withServer } from './server.js'
6
+
7
+ const BACKUP = '/app/node_modules/.bin/ramdb2-server-backup'
8
+
9
+ /**
10
+ * The backups of a site, oldest first.
11
+ * @param {import('./config.js').Infra} infra
12
+ * @param {string} site
13
+ * @param {{run?: import('./server.js').Runner}} [options]
14
+ * @returns {Promise<string[]>}
15
+ */
16
+ export async function listBackups(infra, site, { run = runCommand } = {}) {
17
+ return withServer(infra, serverOf(infra, site), run, async ({ compose, env }) => {
18
+ const result = await run('docker', [...compose, 'run', '--rm', '--no-deps', '-T', '-e', 'LOG_LEVEL=warn',
19
+ `${site}-backup`, BACKUP, 'list'], { env, capture: true })
20
+ if (result.code !== 0) throw new Error(`The backups of ${site} could not be listed: ${result.stderr.trim()}`)
21
+ return result.stdout.split('\n').filter(line => line !== '')
22
+ })
23
+ }
24
+
25
+ /**
26
+ * Restores the last backup of a site at or before `moment` (UTC; the last one by default): stops its API and its
27
+ * backups, restores, starts them again, even when the restore failed (the database is then unchanged).
28
+ * @param {import('./config.js').Infra} infra
29
+ * @param {string} site
30
+ * @param {object} [options]
31
+ * @param {string} [options.moment]
32
+ * @param {import('./server.js').Runner} [options.run]
33
+ * @param {(line: string) => void} [options.print]
34
+ */
35
+ export async function restore(infra, site, { moment, run = runCommand, print = console.log } = {}) {
36
+ const server = serverOf(infra, site)
37
+ return withServer(infra, server, run, async ({ compose, env }) => {
38
+ const services = [`${site}-api`, `${site}-backup`]
39
+ print(`${site}: stopping ${services.join(', ')} on ${server}`)
40
+ await check(run('docker', [...compose, 'stop', ...services], { env }), 'docker compose stop')
41
+ let restored
42
+ try {
43
+ restored = await run('docker', [...compose, 'run', '--rm', '--no-deps', '-T', `${site}-backup`, BACKUP, 'restore',
44
+ ...(moment === undefined ? [] : [moment])], { env })
45
+ } finally {
46
+ print(`${site}: starting ${services.join(', ')}`)
47
+ await check(run('docker', [...compose, 'start', ...services], { env }), 'docker compose start')
48
+ }
49
+ if (restored.code !== 0) throw new Error(`The restore of ${site} failed: its database is unchanged`)
50
+ print(`${site}: restored`)
51
+ })
52
+ }
53
+
54
+ /**
55
+ * Writes a backup of a site to a local file, decompressed and checked: the last one at or before `moment`.
56
+ * @param {import('./config.js').Infra} infra
57
+ * @param {string} site
58
+ * @param {string} file
59
+ * @param {object} [options]
60
+ * @param {string} [options.moment]
61
+ * @param {import('./server.js').Runner} [options.run]
62
+ */
63
+ export async function fetch(infra, site, file, { moment, run = runCommand } = {}) {
64
+ return withServer(infra, serverOf(infra, site), run, async ({ compose, env }) => {
65
+ // The database comes on the standard output; the messages of the command go to the error output
66
+ const script = `${BACKUP} fetch /tmp/fetched.db "$@" >&2 && cat /tmp/fetched.db`
67
+ const part = `${file}.part`
68
+ try {
69
+ const result = await run('docker', [...compose, 'run', '--rm', '--no-deps', '-T', '-e', 'LOG_LEVEL=warn',
70
+ `${site}-backup`, 'sh', '-c', script, 'sh', ...(moment === undefined ? [] : [moment])], { env, stdout: part })
71
+ if (result.code !== 0) throw new Error(`The backup of ${site} could not be fetched`)
72
+ renameSync(part, file)
73
+ } finally {
74
+ rmSync(part, { force: true })
75
+ }
76
+ })
77
+ }
@@ -0,0 +1,41 @@
1
+ // ramdb2-cli infra deploy (D55): build, decrypt the secrets with sops, docker compose up on the server through
2
+ // DOCKER_HOST=ssh://, then the Let's Encrypt certificates, and nginx reloaded.
3
+ import { readFileSync } from 'node:fs'
4
+ import { join } from 'node:path'
5
+ import { check, runCommand, withServer } from './server.js'
6
+
7
+ /**
8
+ * Deploys one server.
9
+ * @param {import('./config.js').Infra} infra
10
+ * @param {string} name the server
11
+ * @param {object} [options]
12
+ * @param {boolean} [options.staging] the staging certificates of Let's Encrypt (not trusted by browsers, no rate limit)
13
+ * @param {import('./server.js').Runner} [options.run]
14
+ * @param {(line: string) => void} [options.print]
15
+ * @returns {Promise<{certificates: {name: string, ok: boolean}[]}>}
16
+ */
17
+ export function deploy(infra, name, { staging = false, run = runCommand, print = console.log } = {}) {
18
+ return withServer(infra, name, run, async ({ server, dir, compose, env }) => {
19
+ print(`${name}: files written in ${dir}`)
20
+ print(`${name}: docker compose up on ${server.host}`)
21
+ await check(run('docker', [...compose, 'up', '-d', '--build', '--remove-orphans'], { env }), 'docker compose up')
22
+
23
+ const certificates = []
24
+ for (const certificate of JSON.parse(readFileSync(join(dir, 'certificates.json'), 'utf8'))) {
25
+ print(`${name}: certificate ${certificate.name} (${certificate.domains.join(', ')})`)
26
+ const result = await run('docker', [...compose, 'run', '--rm', '--entrypoint', 'certbot', 'certbot',
27
+ 'certonly', '--webroot', '-w', '/var/www/certbot', '--cert-name', certificate.name,
28
+ ...certificate.domains.flatMap(domain => ['-d', domain]),
29
+ '--email', server.email, '--agree-tos', '--no-eff-email', '--non-interactive', '--keep-until-expiring',
30
+ ...(staging ? ['--staging'] : [])], { env })
31
+ if (result.code !== 0) print(`${name}: certificate ${certificate.name} not obtained: do its domains point to the server?`)
32
+ certificates.push({ name: certificate.name, ok: result.code === 0 })
33
+ }
34
+ if (certificates.length > 0) {
35
+ await check(run('docker', [...compose, 'exec', '-T', 'nginx', 'sh', '-c', 'ramdb2-certs && nginx -s reload'], { env }),
36
+ 'nginx reload')
37
+ }
38
+ print(`${name}: deployed`)
39
+ return { certificates }
40
+ })
41
+ }
@@ -0,0 +1,19 @@
1
+ // ramdb2-cli infra down (D55): stops and removes the containers and the network of a server. The volumes (the
2
+ // databases), the images and the certificates stay: infra deploy starts the server again as it was.
3
+ import { check, runCommand, withServer } from './server.js'
4
+
5
+ /**
6
+ * Stops one server. Its secrets are decrypted too: Compose needs them to read compose.yaml.
7
+ * @param {import('./config.js').Infra} infra
8
+ * @param {string} name the server
9
+ * @param {object} [options]
10
+ * @param {import('./server.js').Runner} [options.run]
11
+ * @param {(line: string) => void} [options.print]
12
+ */
13
+ export async function down(infra, name, { run = runCommand, print = console.log } = {}) {
14
+ return withServer(infra, name, run, async ({ server, compose, env }) => {
15
+ print(`${name}: docker compose down on ${server.host} (the volumes stay)`)
16
+ await check(run('docker', [...compose, 'down', '--remove-orphans'], { env }), 'docker compose down')
17
+ print(`${name}: stopped`)
18
+ })
19
+ }
@@ -0,0 +1,54 @@
1
+ // ramdb2-cli infra keygen (D56): the SSH key of a server for its backups, encrypted by sops in secrets/<server>.key,
2
+ // its public half in secrets/<server>.pub, to install on the backup server.
3
+ import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
4
+ import { tmpdir } from 'node:os'
5
+ import { join } from 'node:path'
6
+ import { runCommand } from './server.js'
7
+
8
+ /**
9
+ * Creates the backup key of a server. An existing key is replaced only with `force`.
10
+ * @param {import('./config.js').Infra} infra
11
+ * @param {string} name the server
12
+ * @param {object} [options]
13
+ * @param {boolean} [options.force]
14
+ * @param {import('./server.js').Runner} [options.run]
15
+ * @param {(line: string) => void} [options.print]
16
+ * @returns {Promise<{publicKey: string, files: string[]}>}
17
+ */
18
+ export async function keygen(infra, name, { force = false, run = runCommand, print = console.log } = {}) {
19
+ if (!infra.servers.some(server => server.name === name)) throw new Error(`No server ${name} in infra.yaml`)
20
+ const key = join(infra.dir, 'secrets', `${name}.key`)
21
+ const pub = join(infra.dir, 'secrets', `${name}.pub`)
22
+ if (existsSync(key) && !force) {
23
+ throw new Error(`secrets/${name}.key exists: --force replaces it (then install the new public key on the backup server)`)
24
+ }
25
+ if (!existsSync(join(infra.dir, '.sops.yaml'))) {
26
+ throw new Error('No .sops.yaml in the infra folder: it gives the age keys that encrypt secrets/ (see the README of ramdb2-cli)')
27
+ }
28
+ const work = mkdtempSync(join(tmpdir(), 'ramdb2-keygen-'))
29
+ chmodSync(work, 0o700)
30
+ try {
31
+ const comment = `ramdb2-backup-${name}`
32
+ const generated = await run('ssh-keygen', ['-q', '-t', 'ed25519', '-N', '', '-C', comment, '-f', join(work, 'key')], { capture: true })
33
+ if (generated.code !== 0) throw new Error(`ssh-keygen failed: ${generated.stderr.trim()}`)
34
+ // The rules of .sops.yaml are matched on the input file name: the final name is given instead
35
+ const encrypted = await run('sops', ['--encrypt', '--input-type', 'binary', '--output-type', 'binary',
36
+ '--filename-override', `secrets/${name}.key`, join(work, 'key')], { capture: true, cwd: infra.dir })
37
+ if (encrypted.code !== 0) throw new Error(`sops could not encrypt the key: ${encrypted.stderr.trim()}`)
38
+ mkdirSync(join(infra.dir, 'secrets'), { recursive: true })
39
+ writeFileSync(`${key}.part`, encrypted.stdout, { mode: 0o600 })
40
+ renameSync(`${key}.part`, key)
41
+ const publicKey = readFileSync(join(work, 'key.pub'), 'utf8').trim()
42
+ writeFileSync(pub, publicKey + '\n')
43
+ print(`written ${key} (encrypted by sops)`)
44
+ print(`written ${pub}`)
45
+ print(`\nThe public key of ${name}, for ~backup/.ssh/authorized_keys on the backup server (restrict: no shell,`)
46
+ print('no forwarding; the SFTP-only access comes from the sshd configuration, see the README of ramdb2-cli):\n')
47
+ print(`restrict ${publicKey}`)
48
+ print(`\nThen: ramdb2-cli infra deploy ${name}`)
49
+ return { publicKey, files: [key, pub] }
50
+ } finally {
51
+ rmSync(work, { recursive: true, force: true })
52
+ rmSync(`${key}.part`, { force: true })
53
+ }
54
+ }
@@ -0,0 +1,106 @@
1
+ // What the infra commands that talk to a server share: the files built, the secrets decrypted by sops into a
2
+ // private temporary folder, the environment of docker compose (DOCKER_HOST and the secrets) and the commands run.
3
+ import { spawn } from 'node:child_process'
4
+ import { chmodSync, createWriteStream, existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
5
+ import { join } from 'node:path'
6
+ import { buildInfra } from './build.js'
7
+
8
+ /**
9
+ * Runs a command; its output goes to the terminal unless `capture`. `stdout` may be a file, for binary output.
10
+ * @typedef {(command: string, args: string[], options?: {env?: Record<string, string>, capture?: boolean,
11
+ * cwd?: string, stdout?: string}) => Promise<{code: number, stdout: string, stderr: string}>} Runner
12
+ */
13
+
14
+ /**
15
+ * @typedef {object} Connection
16
+ * @property {import('./config.js').Server} server
17
+ * @property {string} dir build/<server>/
18
+ * @property {string[]} compose `compose -f build/<server>/compose.yaml`, for docker
19
+ * @property {Record<string, string>} env DOCKER_HOST, RAMDB2_SECRETS and BACKUP_SSH_KEY
20
+ */
21
+
22
+ /**
23
+ * Builds the files of a server, decrypts its secrets, runs `action`, then deletes the decrypted secrets.
24
+ * Stops before `action` when a secret is missing or cannot be decrypted.
25
+ * @template T
26
+ * @param {import('./config.js').Infra} infra
27
+ * @param {string} name the server
28
+ * @param {Runner} run
29
+ * @param {(connection: Connection) => Promise<T>} action
30
+ * @returns {Promise<T>}
31
+ */
32
+ export async function withServer(infra, name, run, action) {
33
+ const [{ dir }] = buildInfra(infra, [name])
34
+ const server = infra.servers.find(candidate => candidate.name === name)
35
+ const missing = server.sites.map(site => `secrets/${site.name}.env`)
36
+ .concat(server.sites.length > 0 ? [`secrets/${name}.key`] : [])
37
+ .filter(path => !existsSync(join(infra.dir, path)))
38
+ if (missing.length > 0) {
39
+ throw new Error(`Missing secrets, encrypted with sops: ${missing.join(', ')}`
40
+ + (missing.includes(`secrets/${name}.key`) ? ` (ramdb2-cli infra keygen ${name} creates the key)` : ''))
41
+ }
42
+ // In build/<server>/, not in the system temporary folder: Docker installed as a snap cannot read /tmp
43
+ const secrets = mkdtempSync(join(dir, '.secrets-'))
44
+ chmodSync(secrets, 0o700)
45
+ try {
46
+ const env = { DOCKER_HOST: server.host, RAMDB2_SECRETS: secrets, BACKUP_SSH_KEY: '' }
47
+ for (const site of server.sites) {
48
+ const values = await decrypt(run, join(infra.dir, 'secrets', `${site.name}.env`), 'dotenv')
49
+ writeFileSync(join(secrets, `${site.name}.env`), values, { mode: 0o600 })
50
+ }
51
+ if (server.sites.length > 0) env.BACKUP_SSH_KEY = await decrypt(run, join(infra.dir, 'secrets', `${name}.key`), 'binary')
52
+ return await action({ server, dir, compose: ['compose', '-f', join(dir, 'compose.yaml')], env })
53
+ } finally {
54
+ rmSync(secrets, { recursive: true, force: true })
55
+ }
56
+ }
57
+
58
+ /**
59
+ * The server of a site: a site name is unique on all the servers.
60
+ * @param {import('./config.js').Infra} infra
61
+ * @param {string} site
62
+ * @returns {string}
63
+ */
64
+ export function serverOf(infra, site) {
65
+ const server = infra.servers.find(candidate => candidate.sites.some(entry => entry.name === site))
66
+ if (server === undefined) throw new Error(`No ramdb2 site ${site} in infra.yaml`)
67
+ return server.name
68
+ }
69
+
70
+ async function decrypt(run, file, type) {
71
+ const result = await run('sops', ['--decrypt', '--input-type', type, '--output-type', type, file], { capture: true })
72
+ if (result.code !== 0) throw new Error(`sops could not decrypt ${file}: ${result.stderr.trim()}`)
73
+ return result.stdout
74
+ }
75
+
76
+ /**
77
+ * Fails with `what` when the command failed.
78
+ * @param {Promise<{code: number}>} promise
79
+ * @param {string} what
80
+ */
81
+ export async function check(promise, what) {
82
+ const result = await promise
83
+ if (result.code !== 0) throw new Error(`${what} failed (exit code ${result.code})`)
84
+ return result
85
+ }
86
+
87
+ /** @type {Runner} */
88
+ export function runCommand(command, args, { env = {}, capture = false, cwd, stdout: outputFile } = {}) {
89
+ return new Promise((resolve, reject) => {
90
+ const child = spawn(command, args, {
91
+ env: { ...process.env, ...env },
92
+ cwd,
93
+ stdio: ['inherit', capture || outputFile !== undefined ? 'pipe' : 'inherit', capture ? 'pipe' : 'inherit'],
94
+ })
95
+ let stdout = ''
96
+ let stderr = ''
97
+ // With an output file, the command is done once the file is written too
98
+ const file = outputFile === undefined ? null : createWriteStream(outputFile)
99
+ const written = file === null ? Promise.resolve() : new Promise((done, fail) => file.on('finish', done).on('error', fail))
100
+ if (file !== null) child.stdout.pipe(file)
101
+ else child.stdout?.on('data', chunk => { stdout += chunk })
102
+ child.stderr?.on('data', chunk => { stderr += chunk })
103
+ child.on('error', error => reject(error.code === 'ENOENT' ? new Error(`${command} is not installed`) : error))
104
+ child.on('close', code => written.then(() => resolve({ code, stdout, stderr }), reject))
105
+ })
106
+ }
package/src/model.js CHANGED
@@ -64,6 +64,8 @@ export class SchemaError extends Error {
64
64
  * @property {string | undefined} description
65
65
  * @property {boolean} scalar scalar, enum, custom scalar or a list of them (a type of another layer is a scalar)
66
66
  * @property {string[]} requiredArgs arguments without a default value
67
+ * @property {boolean} getter @transient(getter: true): a getter of the class gives its value, a query filters and
68
+ * sorts on it (D62)
67
69
  *
68
70
  * @typedef {object} Index
69
71
  * @property {string} name
@@ -82,6 +84,10 @@ export class SchemaError extends Error {
82
84
  * @property {Computed[]} computed
83
85
  * @property {Transient[]} transient fields resolved by the project on the server
84
86
  * @property {Index[]} indexes declared with @index (the inverse indexes of the foreign keys are automatic)
87
+ * @property {string[]} restricted @restricted fields (D58): stored fields, relations with their foreign key,
88
+ * computed and @transient fields
89
+ * @property {Record<string, 'date' | 'datetime'>} dates the Int fields of @date and @datetime (D64): stored, computed
90
+ * or @transient
85
91
  *
86
92
  * @typedef {object} Model
87
93
  * @property {Type[]} types
@@ -136,6 +142,8 @@ export function readSchema(source) {
136
142
  computed: [],
137
143
  transient: [],
138
144
  indexes: [],
145
+ restricted: [],
146
+ dates: {},
139
147
  _gql: gqlType,
140
148
  }
141
149
  types.push(type)
@@ -155,7 +163,8 @@ export function readSchema(source) {
155
163
  const list = isListType(isNonNullType(gqlField.type) ? gqlField.type.ofType : gqlField.type)
156
164
  const description = gqlField.description ?? undefined
157
165
  const computed = values('computed', node)
158
- const transient = values('transient', node) !== undefined
166
+ const transientArgs = values('transient', node)
167
+ const transient = transientArgs !== undefined
159
168
  const pattern = values('pattern', node)
160
169
  const onDelete = values('onDelete', node)
161
170
  const field = values('field', node)
@@ -163,6 +172,22 @@ export function readSchema(source) {
163
172
  if (isPrivate && (computed !== undefined || transient || name === 'id' || isObjectType(named) || list)) {
164
173
  errors.push(`${at(name)}: @private only goes on a stored scalar field`)
165
174
  }
175
+ // A date is an Int of Unix seconds, whatever the field: stored, computed or @transient (D64)
176
+ const dateKinds = ['date', 'datetime'].filter(kind => values(kind, node) !== undefined)
177
+ if (dateKinds.length > 1) errors.push(`${at(name)}: @date and @datetime exclude each other`)
178
+ else if (dateKinds.length === 1) {
179
+ if (named.name !== 'Int' || list || name === 'id') errors.push(`${at(name)}: @${dateKinds[0]} only goes on an Int field (Unix seconds), not on the id`)
180
+ else type.dates[name] = dateKinds[0]
181
+ }
182
+ if (values('restricted', node) !== undefined) {
183
+ if (name === 'id') errors.push(`${at(name)}: the id cannot be @restricted`)
184
+ else if (isPrivate) errors.push(`${at(name)}: @private and @restricted exclude each other`)
185
+ else if (list && isPersistent(named)) errors.push(`${at(name)}: a list relation cannot be @restricted: restrict the object relation of the other type`)
186
+ else {
187
+ type.restricted.push(name)
188
+ if (isPersistent(named) && computed === undefined && !transient) type.restricted.push('id' + upperFirst(name))
189
+ }
190
+ }
166
191
 
167
192
  if (computed !== undefined && transient) errors.push(`${at(name)}: @computed and @transient exclude each other`)
168
193
  if (computed !== undefined) {
@@ -177,7 +202,12 @@ export function readSchema(source) {
177
202
  description,
178
203
  scalar: isLeafType(named),
179
204
  requiredArgs: gqlField.args.filter(arg => isNonNullType(arg.type) && arg.defaultValue === undefined).map(arg => arg.name),
205
+ getter: transientArgs.getter === true,
180
206
  })
207
+ // A getter reads the object alone: one scalar value, no argument (filtered and sorted by the engine)
208
+ if (transientArgs.getter === true && (!isLeafType(named) || list || gqlField.args.length > 0)) {
209
+ errors.push(`${at(name)}: @transient(getter: true) only goes on a scalar field without arguments`)
210
+ }
181
211
  continue
182
212
  }
183
213
  if (name === 'id') {
@@ -236,6 +266,7 @@ export function readSchema(source) {
236
266
  checkRelations(types, byName, errors)
237
267
  for (const type of types) readIndexes(type, values, errors)
238
268
  for (const type of types) checkComputed(type, byName, errors)
269
+ for (const type of types) checkRestrictedDependencies(type, byName, errors)
239
270
 
240
271
  if (errors.length > 0) throw new SchemaError(errors)
241
272
  for (const type of types) delete type._gql
@@ -358,6 +389,25 @@ function checkComputed(type, byName, errors) {
358
389
  for (const name of local.keys()) visit(name, [])
359
390
  }
360
391
 
392
+ // A computed field that depends on a @restricted field would reveal it: it must be @restricted too (D58).
393
+ // A path is restricted when it ends on a restricted field, goes through a restricted relation, or goes through a
394
+ // list relation whose foreign key is restricted (the list tells which objects point here).
395
+ function checkRestrictedDependencies(type, byName, errors) {
396
+ for (const computed of type.computed) {
397
+ if (type.restricted.includes(computed.name)) continue
398
+ for (const path of computed.depends) {
399
+ const { steps, end, last, error } = resolvePath(type, path.split('.'), byName)
400
+ if (error !== undefined) continue
401
+ const through = steps.some(step => step.kind === 'parent'
402
+ ? step.from.restricted.includes(step.relation.name)
403
+ : step.to.restricted.includes(step.relation.fk))
404
+ if (through || (last !== undefined && end.restricted.includes(last))) {
405
+ errors.push(`${type.name}.${computed.name}: depends on "${path}", which is @restricted: add @restricted to ${computed.name}`)
406
+ }
407
+ }
408
+ }
409
+ }
410
+
361
411
  /**
362
412
  * Follows a dependency path from a type.
363
413
  * @returns {{steps?: {relation: Parent | Child, kind: 'parent' | 'child', from: Type, to: Type}[], end?: Type, last?: string, error?: string}}
package/src/new.js CHANGED
@@ -148,6 +148,8 @@ type Task @persistent {
148
148
  project: Project!
149
149
  name: String!
150
150
  hours: Float!
151
+ "Due day: the Unix seconds of its midnight UTC, null for no date (@date, D64)"
152
+ due: Int @date
151
153
  }
152
154
 
153
155
  enum UserRole { USER ADMIN }