ramdb2-cli 2.0.0-alpha.2 → 2.0.0-alpha.4

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,18 @@
1
1
  # ramdb2-cli
2
2
 
3
+ ## 2.0.0-alpha.4
4
+
5
+ ### Minor Changes
6
+
7
+ - 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.
8
+ - 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`.
9
+
10
+ ## 2.0.0-alpha.3
11
+
12
+ ### Minor Changes
13
+
14
+ - 92570bd: `ramdb2-cli infra down <server>`: stops a server (docker compose down), keeps its volumes; asks first, unless `--yes`.
15
+
3
16
  ## 2.0.0-alpha.2
4
17
 
5
18
  ### Minor Changes
package/README.md CHANGED
@@ -42,7 +42,7 @@ 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
@@ -99,6 +99,7 @@ a directive in the wrong place, a missing or badly typed argument is an error.
99
99
  | `@transient` | field | | a field of the API that is not stored |
100
100
  | `@sensitive` | field | | its value is masked in the logs of ramdb2-server (`"[REDACTED]"`) |
101
101
  | `@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 |
102
+ | `@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
103
 
103
104
  ### How the fields are read
104
105
 
@@ -444,6 +445,17 @@ not point to the server yet) does not stop the others; the exit code is then 1.
444
445
  The decrypted secrets live in `build/<server>/.secrets-*` (only you can read it) while a command runs, and are
445
446
  deleted at the end, even on an error. Not in `/tmp`: Docker installed as a snap cannot read it.
446
447
 
448
+ ### Stop a server
449
+
450
+ ```sh
451
+ ramdb2-cli infra down ovh1 # asks first; --yes to skip the question
452
+ ```
453
+
454
+ `down` runs `docker compose down --remove-orphans` on the server: the containers of all its sites (ramdb2 and
455
+ custom) and its network are removed. The volumes (the databases, the backup queues), the images and the
456
+ certificates stay: `ramdb2-cli infra deploy ovh1` starts the server again as it was. Like every command that talks
457
+ to a server, it decrypts the secrets: Compose needs them to read `compose.yaml`.
458
+
447
459
  ### Secrets: sops and age, once
448
460
 
449
461
  ```sh
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ramdb2-cli",
3
- "version": "2.0.0-alpha.2",
3
+ "version": "2.0.0-alpha.4",
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.2",
31
+ "ramdb2-core": "^2.0.0-alpha.4",
32
32
  "vite": "^8.3.5",
33
33
  "vue": "^3.5.44",
34
34
  "vue-router": "^5.4.0"
package/src/cli.js CHANGED
@@ -9,6 +9,7 @@ import { query } from './query.js'
9
9
  import { readInfra } from './infra/config.js'
10
10
  import { buildInfra } from './infra/build.js'
11
11
  import { deploy } from './infra/deploy.js'
12
+ import { down } from './infra/down.js'
12
13
  import { keygen } from './infra/keygen.js'
13
14
  import { fetch as fetchBackup, listBackups, restore } from './infra/backups.js'
14
15
  import { createInterface } from 'node:readline/promises'
@@ -50,6 +51,10 @@ const HELP = `ramdb2-cli: code generator of ramdb2
50
51
  on the server (DOCKER_HOST=ssh://...), the missing Let's Encrypt certificates, and nginx reloaded.
51
52
  --staging: the test certificates of Let's Encrypt, not trusted by browsers.
52
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
+
53
58
  ramdb2-cli infra keygen <server> [--force]
54
59
  Creates the SSH key of the server for its backups: secrets/<server>.key, encrypted by sops (.sops.yaml),
55
60
  and secrets/<server>.pub, printed, to install on the backup server. --force replaces an existing key.
@@ -129,7 +134,7 @@ function report({ written, kept, warnings }) {
129
134
  }
130
135
 
131
136
  async function infra(values, [action, ...args]) {
132
- const actions = ['build', 'deploy', 'keygen', 'backups', 'restore', 'fetch']
137
+ const actions = ['build', 'deploy', 'down', 'keygen', 'backups', 'restore', 'fetch']
133
138
  if (!actions.includes(action)) return usage(`infra needs an action: ${actions.join(', ')}`)
134
139
  const infra = readInfra(values.config ?? 'infra.yaml')
135
140
  switch (action) {
@@ -145,6 +150,15 @@ async function infra(values, [action, ...args]) {
145
150
  if (certificates.some(certificate => !certificate.ok)) process.exitCode = 1
146
151
  return
147
152
  }
153
+ case 'down':
154
+ if (args.length !== 1) return usage('infra down needs one server')
155
+ if (!infra.servers.some(server => server.name === args[0])) throw new Error(`No server ${args[0]} in infra.yaml`)
156
+ if (!values.yes && !(await confirm(`Stop all the sites of ${args[0]}? Their data stays. [y/N] `))) {
157
+ console.log('Nothing done')
158
+ return
159
+ }
160
+ await down(infra, args[0])
161
+ return
148
162
  case 'keygen':
149
163
  if (args.length !== 1) return usage('infra keygen needs one server')
150
164
  await keygen(infra, args[0], { force: values.force ?? false })
package/src/directives.js CHANGED
@@ -33,10 +33,13 @@ directive @transient on FIELD_DEFINITION
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'])
@@ -40,6 +40,18 @@ 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.children.length > 0) {
49
+ lines.push('')
50
+ lines.push(' // The list relations: the table of their objects and the foreign key that points here')
51
+ lines.push(' static listRelations = {')
52
+ for (const child of type.children) lines.push(` ${child.name}: { table: '${byNameTable(model, child.target)}', key: '${child.fk}' },`)
53
+ lines.push(' }')
54
+ }
43
55
 
44
56
  const foreignKeys = type.parents.map(parent => [parent, onDeleteOf(parent, type, model)])
45
57
  if (foreignKeys.length > 0) {
@@ -290,3 +302,7 @@ export function jsdoc(description, indent, extra = []) {
290
302
  export function quote(string) {
291
303
  return `'${string}'`
292
304
  }
305
+
306
+ function byNameTable(model, name) {
307
+ return model.byName.get(name).table
308
+ }
@@ -89,34 +89,39 @@ function generatedClass(type, model) {
89
89
  lines.push(' }')
90
90
  }
91
91
 
92
+ // A @restricted field may be hidden by its permission on the server (D58): null
93
+ const orNull = (name, jsType) => type.restricted.includes(name) && !/\bnull\b/.test(jsType) ? `${jsType} | null` : jsType
92
94
  for (const parent of type.parents) {
93
95
  lines.push('')
94
- lines.push(` /** @returns {number} foreign key of ${parent.name}, 0 = none */`)
96
+ lines.push(` /** @returns {${orNull(parent.fk, 'number')}} foreign key of ${parent.name}, 0 = none */`)
95
97
  lines.push(` get ${parent.fk}() { return this._f.${parent.fk} }`)
96
98
  }
97
99
  for (const field of fields) {
98
100
  lines.push('')
99
- lines.push(jsdoc(field.description, ' ', [`@returns {${field.jsType}}`]))
101
+ lines.push(jsdoc(field.description, ' ', [`@returns {${orNull(field.name, field.jsType)}}`]))
100
102
  lines.push(` get ${field.name}() { return this._f.${field.name} }`)
101
103
  }
102
104
  for (const relation of [...type.parents, ...type.children]) {
103
105
  const target = model.byName.get(relation.target)
104
- const list = type.children.includes(relation) ? '[]' : ''
106
+ // An object relation may be hidden by the permission see of the server (D57): null
107
+ const returns = type.children.includes(relation) ? '[]' : ' | null'
105
108
  lines.push('')
106
109
  lines.push(jsdoc(relation.description, ' ', [
107
110
  `Loaded with include: ['${relation.name}'].`,
108
- `@returns {import('../extended/${target.table}.js').default${list}}`,
111
+ `@returns {import('../extended/${target.table}.js').default${returns}}`,
109
112
  ]))
110
113
  lines.push(` get ${relation.name}() { return this._relation('${relation.name}') }`)
111
114
  }
112
115
  for (const computed of type.computed) {
113
116
  lines.push('')
114
- lines.push(jsdoc(computed.description, ' ', ['Computed by the server.', `@returns {${computed.jsType}}`]))
117
+ // Served nullable when it leads to one persistent object (D57)
118
+ const served = /^\w+!$/.test(computed.display) && model.byName.has(computed.display.slice(0, -1)) ? `${computed.jsType} | null` : computed.jsType
119
+ lines.push(jsdoc(computed.description, ' ', ['Computed by the server.', `@returns {${orNull(computed.name, served)}}`]))
115
120
  lines.push(` get ${computed.name}() { return this._c.${computed.name} }`)
116
121
  }
117
122
  for (const field of transient) {
118
123
  lines.push('')
119
- lines.push(jsdoc(field.description, ' ', ['Resolved by the project on the server.', `@returns {${field.jsType}}`]))
124
+ lines.push(jsdoc(field.description, ' ', ['Resolved by the project on the server.', `@returns {${orNull(field.name, field.jsType)}}`]))
120
125
  lines.push(` get ${field.name}() { return this._c.${field.name} }`)
121
126
  }
122
127
  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/index.js CHANGED
@@ -9,5 +9,6 @@ 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
11
  export { deploy } from './infra/deploy.js'
12
+ export { down } from './infra/down.js'
12
13
  export { keygen } from './infra/keygen.js'
13
14
  export { listBackups, restore, fetch as fetchBackup } from './infra/backups.js'
@@ -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
+ }
package/src/model.js CHANGED
@@ -82,6 +82,8 @@ export class SchemaError extends Error {
82
82
  * @property {Computed[]} computed
83
83
  * @property {Transient[]} transient fields resolved by the project on the server
84
84
  * @property {Index[]} indexes declared with @index (the inverse indexes of the foreign keys are automatic)
85
+ * @property {string[]} restricted @restricted fields (D58): stored fields, relations with their foreign key,
86
+ * computed and @transient fields
85
87
  *
86
88
  * @typedef {object} Model
87
89
  * @property {Type[]} types
@@ -136,6 +138,7 @@ export function readSchema(source) {
136
138
  computed: [],
137
139
  transient: [],
138
140
  indexes: [],
141
+ restricted: [],
139
142
  _gql: gqlType,
140
143
  }
141
144
  types.push(type)
@@ -163,6 +166,15 @@ export function readSchema(source) {
163
166
  if (isPrivate && (computed !== undefined || transient || name === 'id' || isObjectType(named) || list)) {
164
167
  errors.push(`${at(name)}: @private only goes on a stored scalar field`)
165
168
  }
169
+ if (values('restricted', node) !== undefined) {
170
+ if (name === 'id') errors.push(`${at(name)}: the id cannot be @restricted`)
171
+ else if (isPrivate) errors.push(`${at(name)}: @private and @restricted exclude each other`)
172
+ else if (list && isPersistent(named)) errors.push(`${at(name)}: a list relation cannot be @restricted: restrict the object relation of the other type`)
173
+ else {
174
+ type.restricted.push(name)
175
+ if (isPersistent(named) && computed === undefined && !transient) type.restricted.push('id' + upperFirst(name))
176
+ }
177
+ }
166
178
 
167
179
  if (computed !== undefined && transient) errors.push(`${at(name)}: @computed and @transient exclude each other`)
168
180
  if (computed !== undefined) {
@@ -236,6 +248,7 @@ export function readSchema(source) {
236
248
  checkRelations(types, byName, errors)
237
249
  for (const type of types) readIndexes(type, values, errors)
238
250
  for (const type of types) checkComputed(type, byName, errors)
251
+ for (const type of types) checkRestrictedDependencies(type, byName, errors)
239
252
 
240
253
  if (errors.length > 0) throw new SchemaError(errors)
241
254
  for (const type of types) delete type._gql
@@ -358,6 +371,25 @@ function checkComputed(type, byName, errors) {
358
371
  for (const name of local.keys()) visit(name, [])
359
372
  }
360
373
 
374
+ // A computed field that depends on a @restricted field would reveal it: it must be @restricted too (D58).
375
+ // A path is restricted when it ends on a restricted field, goes through a restricted relation, or goes through a
376
+ // list relation whose foreign key is restricted (the list tells which objects point here).
377
+ function checkRestrictedDependencies(type, byName, errors) {
378
+ for (const computed of type.computed) {
379
+ if (type.restricted.includes(computed.name)) continue
380
+ for (const path of computed.depends) {
381
+ const { steps, end, last, error } = resolvePath(type, path.split('.'), byName)
382
+ if (error !== undefined) continue
383
+ const through = steps.some(step => step.kind === 'parent'
384
+ ? step.from.restricted.includes(step.relation.name)
385
+ : step.to.restricted.includes(step.relation.fk))
386
+ if (through || (last !== undefined && end.restricted.includes(last))) {
387
+ errors.push(`${type.name}.${computed.name}: depends on "${path}", which is @restricted: add @restricted to ${computed.name}`)
388
+ }
389
+ }
390
+ }
391
+ }
392
+
361
393
  /**
362
394
  * Follows a dependency path from a type.
363
395
  * @returns {{steps?: {relation: Parent | Child, kind: 'parent' | 'child', from: Type, to: Type}[], end?: Type, last?: string, error?: string}}