@git.zone/cli 11.0.2 → 12.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,378 @@
1
+ import * as plugins from './mod.plugins.js';
2
+ import {
3
+ getServiceDataDirectory,
4
+ noSqlDbImage,
5
+ serviceDataOwner,
6
+ writeJsonFileAtomically,
7
+ } from './classes.servicedatamarker.js';
8
+
9
+ /*
10
+ * Which database engine wrote a project's `.nogit/nosqldbdata`.
11
+ *
12
+ * The engine itself records no writer version in its root, and an engine
13
+ * move is one-way, so GitZone starts NoSQLDB only on data it can prove the
14
+ * pinned `noSqlDbImage` already owns: an owned container on the pin that has
15
+ * run on this folder, or the engine record below. Everything else is refused
16
+ * until `gitzone services upgrade mongodb` moves it on request.
17
+ */
18
+
19
+ /** Engine record file name, stored in `<projectPath>/.nogit/`. */
20
+ export const noSqlDbEngineRecordFile = '.gitzone-nosqldb-engine.json';
21
+
22
+ /** Database release of `noSqlDbImage`; moves with the pin. */
23
+ export const noSqlDbEngineRelease = '4.0.0';
24
+
25
+ /** The first gitzone release that ran `noSqlDbImage`; moves with the pin. */
26
+ export const noSqlDbEngineFirstCliRelease = '12.0.0';
27
+
28
+ /**
29
+ * Images that earlier gitzone releases pinned for the `mongodb` service, by
30
+ * their database release. Only these are called older in messages; any other
31
+ * image is another engine, possibly a newer one.
32
+ */
33
+ export const earlierNoSqlDbEngineReleases: Readonly<Record<string, string>> = {
34
+ 'code.foss.global/lossless.zone/database@sha256:8fed3bc2da051a6ce29906383ea37e3ae777e2a7373869effbd3093fc4a2a650':
35
+ '2.0.0',
36
+ };
37
+
38
+ /** Identity of a data directory, from `lstat` with bigint precision. */
39
+ export interface INoSqlDbDataIdentity {
40
+ device: string;
41
+ inode: string;
42
+ birthtimeNs: string;
43
+ }
44
+
45
+ /**
46
+ * Proof that `image` last opened the directory with exactly this identity.
47
+ * A separate file, never a marker field: gitzone 11 and 12.0.0 refuse a
48
+ * service data marker with keys they do not know.
49
+ */
50
+ export interface INoSqlDbEngineRecord {
51
+ owner: string;
52
+ kind: 'nosqldb-engine';
53
+ projectPath: string;
54
+ dataPath: string;
55
+ dataDirectory: INoSqlDbDataIdentity;
56
+ image: string;
57
+ recordedAt: string;
58
+ }
59
+
60
+ /** The owned `<project>-nosqldb` container, as far as classification needs it. */
61
+ export interface INoSqlDbContainerEvidence {
62
+ id: string;
63
+ name: string;
64
+ image: string;
65
+ status: string;
66
+ running: boolean;
67
+ mountSources: string[];
68
+ }
69
+
70
+ export interface INoSqlDbDataEvidence {
71
+ projectPath: string;
72
+ dataPath: string;
73
+ container?: INoSqlDbContainerEvidence;
74
+ /** Absent when the data directory does not exist. */
75
+ dataDirectory?: INoSqlDbDataIdentity;
76
+ /** A well-formed record, whether or not it matches the directory. */
77
+ record?: INoSqlDbEngineRecord;
78
+ }
79
+
80
+ export type TNoSqlDbDataAssessment = { container?: INoSqlDbContainerEvidence } & (
81
+ | { kind: 'new' }
82
+ | { kind: 'current'; proof: 'container' | 'record' }
83
+ | { kind: 'other-engine'; proof: 'container' | 'record'; image: string }
84
+ | { kind: 'unclassified' }
85
+ );
86
+
87
+ export type TNoSqlDbDataUpgradeAssessment = Extract<
88
+ TNoSqlDbDataAssessment,
89
+ { kind: 'other-engine' | 'unclassified' }
90
+ >;
91
+
92
+ const dataDirectoryLabel = '.nogit/nosqldbdata';
93
+ const pinnedEngineLabel = `lossless.zone/database ${noSqlDbEngineRelease}`;
94
+ const upgradeCommand = '`gitzone services upgrade mongodb`';
95
+ const identityPattern = /^[0-9]+$/u;
96
+
97
+ const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
98
+ typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
99
+
100
+ const hasExactKeys = (valueArg: Record<string, unknown>, keysArg: readonly string[]): boolean => {
101
+ const keys = Object.keys(valueArg);
102
+ return keys.length === keysArg.length && keysArg.every((keyArg) => keys.includes(keyArg));
103
+ };
104
+
105
+ const isNonEmptyString = (valueArg: unknown): valueArg is string =>
106
+ typeof valueArg === 'string' && valueArg.length > 0;
107
+
108
+ /** Absolute path of the engine record for a project. */
109
+ export const getNoSqlDbEngineRecordPath = (projectPathArg: string): string =>
110
+ plugins.path.join(plugins.path.resolve(projectPathArg), '.nogit', noSqlDbEngineRecordFile);
111
+
112
+ export const isValidNoSqlDbEngineRecord = (
113
+ valueArg: unknown,
114
+ ): valueArg is INoSqlDbEngineRecord => {
115
+ if (
116
+ !isPlainObject(valueArg) ||
117
+ !hasExactKeys(valueArg, [
118
+ 'owner',
119
+ 'kind',
120
+ 'projectPath',
121
+ 'dataPath',
122
+ 'dataDirectory',
123
+ 'image',
124
+ 'recordedAt',
125
+ ]) ||
126
+ valueArg.owner !== serviceDataOwner ||
127
+ valueArg.kind !== 'nosqldb-engine' ||
128
+ !isNonEmptyString(valueArg.projectPath) ||
129
+ !isNonEmptyString(valueArg.dataPath) ||
130
+ !isNonEmptyString(valueArg.image) ||
131
+ !isNonEmptyString(valueArg.recordedAt)
132
+ ) {
133
+ return false;
134
+ }
135
+ const identity = valueArg.dataDirectory;
136
+ return (
137
+ isPlainObject(identity) &&
138
+ hasExactKeys(identity, ['device', 'inode', 'birthtimeNs']) &&
139
+ [identity.device, identity.inode, identity.birthtimeNs].every(
140
+ (partArg) => typeof partArg === 'string' && identityPattern.test(partArg),
141
+ )
142
+ );
143
+ };
144
+
145
+ /**
146
+ * Read the engine record. A missing, unparseable or malformed record is no
147
+ * record; any other read failure is reported, never taken as an answer.
148
+ */
149
+ export const readNoSqlDbEngineRecord = async (
150
+ projectPathArg: string,
151
+ ): Promise<INoSqlDbEngineRecord | undefined> => {
152
+ let content: string;
153
+ try {
154
+ content = await plugins.fs.readFile(getNoSqlDbEngineRecordPath(projectPathArg), 'utf8');
155
+ } catch (error) {
156
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
157
+ return undefined;
158
+ }
159
+ throw error;
160
+ }
161
+ let parsed: unknown;
162
+ try {
163
+ parsed = JSON.parse(content);
164
+ } catch {
165
+ return undefined;
166
+ }
167
+ return isValidNoSqlDbEngineRecord(parsed) ? parsed : undefined;
168
+ };
169
+
170
+ /** Identity of the data directory itself, or undefined when it does not exist. */
171
+ export const readNoSqlDbDataIdentity = async (
172
+ dataPathArg: string,
173
+ ): Promise<INoSqlDbDataIdentity | undefined> => {
174
+ let stats: plugins.fsSync.BigIntStats;
175
+ try {
176
+ stats = await plugins.fs.lstat(dataPathArg, { bigint: true });
177
+ } catch (error) {
178
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
179
+ return undefined;
180
+ }
181
+ throw error;
182
+ }
183
+ if (!stats.isDirectory()) {
184
+ throw new Error(`Refusing NoSQLDB data path that is not a directory: ${dataPathArg}`);
185
+ }
186
+ return {
187
+ device: stats.dev.toString(),
188
+ inode: stats.ino.toString(),
189
+ birthtimeNs: stats.birthtimeNs.toString(),
190
+ };
191
+ };
192
+
193
+ /**
194
+ * Whether a record speaks for exactly this directory. A birth time of 0 is a
195
+ * filesystem without one, where device and inode alone cannot tell a
196
+ * directory from one deleted and created again; it never proves anything.
197
+ */
198
+ export const noSqlDbEngineRecordProvesDirectory = (
199
+ recordArg: INoSqlDbEngineRecord | undefined,
200
+ evidenceArg: Pick<INoSqlDbDataEvidence, 'projectPath' | 'dataPath' | 'dataDirectory'>,
201
+ ): recordArg is INoSqlDbEngineRecord => {
202
+ const identity = evidenceArg.dataDirectory;
203
+ return (
204
+ !!recordArg &&
205
+ !!identity &&
206
+ identity.birthtimeNs !== '0' &&
207
+ recordArg.projectPath === plugins.path.resolve(evidenceArg.projectPath) &&
208
+ recordArg.dataPath === plugins.path.resolve(evidenceArg.dataPath) &&
209
+ recordArg.dataDirectory.device === identity.device &&
210
+ recordArg.dataDirectory.inode === identity.inode &&
211
+ recordArg.dataDirectory.birthtimeNs === identity.birthtimeNs
212
+ );
213
+ };
214
+
215
+ /**
216
+ * Classify a project's NoSQLDB data. Checked in this order:
217
+ * 1. an owned container on an image other than the pin: `other-engine`;
218
+ * 2. an owned container on the pin that has run with this directory as its
219
+ * single bind mount: `current`;
220
+ * 3. no data directory: `new`;
221
+ * 4. a record that matches the directory: `current` on the pin, otherwise
222
+ * `other-engine`;
223
+ * 5. anything else: `unclassified`.
224
+ */
225
+ export const classifyNoSqlDbData = (
226
+ evidenceArg: INoSqlDbDataEvidence,
227
+ ): TNoSqlDbDataAssessment => {
228
+ const container = evidenceArg.container;
229
+ if (container && container.image !== noSqlDbImage) {
230
+ return { kind: 'other-engine', proof: 'container', image: container.image, container };
231
+ }
232
+ if (
233
+ container &&
234
+ container.status !== 'created' &&
235
+ container.mountSources.length === 1 &&
236
+ container.mountSources[0] === plugins.path.resolve(evidenceArg.dataPath)
237
+ ) {
238
+ return { kind: 'current', proof: 'container', container };
239
+ }
240
+ if (!evidenceArg.dataDirectory) {
241
+ return { kind: 'new', container };
242
+ }
243
+ if (noSqlDbEngineRecordProvesDirectory(evidenceArg.record, evidenceArg)) {
244
+ return evidenceArg.record.image === noSqlDbImage
245
+ ? { kind: 'current', proof: 'record', container }
246
+ : { kind: 'other-engine', proof: 'record', image: evidenceArg.record.image, container };
247
+ }
248
+ return { kind: 'unclassified', container };
249
+ };
250
+
251
+ export const noSqlDbDataNeedsUpgrade = (
252
+ assessmentArg: TNoSqlDbDataAssessment,
253
+ ): assessmentArg is TNoSqlDbDataUpgradeAssessment =>
254
+ assessmentArg.kind === 'other-engine' || assessmentArg.kind === 'unclassified';
255
+
256
+ /** Whether two assessments rest on the same evidence. */
257
+ export const sameNoSqlDbDataAssessment = (
258
+ firstArg: TNoSqlDbDataAssessment,
259
+ secondArg: TNoSqlDbDataAssessment,
260
+ ): boolean =>
261
+ firstArg.kind === secondArg.kind &&
262
+ firstArg.container?.id === secondArg.container?.id &&
263
+ firstArg.container?.image === secondArg.container?.image &&
264
+ (firstArg.kind !== 'other-engine' ||
265
+ (secondArg.kind === 'other-engine' &&
266
+ firstArg.proof === secondArg.proof &&
267
+ firstArg.image === secondArg.image));
268
+
269
+ const describeEngineImage = (imageArg: string): string => {
270
+ const release = earlierNoSqlDbEngineReleases[imageArg];
271
+ return release
272
+ ? `${imageArg} (lossless.zone/database ${release}, an older database engine)`
273
+ : `${imageArg}, another database engine`;
274
+ };
275
+
276
+ /** What gitzone knows about the data that needs an upgrade, in one paragraph. */
277
+ const describeNoSqlDbDataEvidence = (assessmentArg: TNoSqlDbDataUpgradeAssessment): string => {
278
+ if (assessmentArg.kind === 'other-engine') {
279
+ return assessmentArg.proof === 'container' && assessmentArg.container
280
+ ? `Container ${assessmentArg.container.name} runs ${describeEngineImage(assessmentArg.image)} on ${dataDirectoryLabel}.`
281
+ : `The engine record of ${dataDirectoryLabel} names ${describeEngineImage(assessmentArg.image)}.`;
282
+ }
283
+ return (
284
+ `gitzone cannot tell which database engine wrote ${dataDirectoryLabel}: no container of this project proves it, ` +
285
+ 'and no engine record matches the folder. ' +
286
+ `If gitzone ${noSqlDbEngineFirstCliRelease} or later last started this project, the folder is already on ${pinnedEngineLabel} ` +
287
+ `and ${upgradeCommand} only records that. ` +
288
+ `If an earlier gitzone release wrote it, the upgrade moves it to ${noSqlDbEngineRelease}, and that move is one-way.`
289
+ );
290
+ };
291
+
292
+ /** The refusal for data this release must not start, or undefined when it may. */
293
+ export const getNoSqlDbDataRefusal = (
294
+ assessmentArg: TNoSqlDbDataAssessment,
295
+ ): string | undefined => {
296
+ if (!noSqlDbDataNeedsUpgrade(assessmentArg)) {
297
+ return undefined;
298
+ }
299
+ const unchanged = assessmentArg.container
300
+ ? 'The folder and the container are unchanged.'
301
+ : 'The folder is unchanged.';
302
+ const consequence =
303
+ assessmentArg.kind === 'other-engine'
304
+ ? `This gitzone runs ${pinnedEngineLabel}, and moving the data to it is one-way. `
305
+ : '';
306
+ return (
307
+ `Refusing to start NoSQLDB: ${describeNoSqlDbDataEvidence(assessmentArg)} ${consequence}${unchanged} ` +
308
+ `Run ${upgradeCommand} to move it, or keep starting this project with the gitzone release that wrote it.`
309
+ );
310
+ };
311
+
312
+ /** What `gitzone services upgrade mongodb` tells the user before it asks. */
313
+ export const describeNoSqlDbUpgrade = (
314
+ assessmentArg: TNoSqlDbDataUpgradeAssessment,
315
+ ): string[] => {
316
+ const container = assessmentArg.container;
317
+ const stopsFirst =
318
+ container && (container.running || container.status === 'restarting')
319
+ ? `stops container ${container.name} gracefully, then `
320
+ : '';
321
+ return [
322
+ describeNoSqlDbDataEvidence(assessmentArg),
323
+ `The upgrade ${stopsFirst}starts NoSQLDB on ${pinnedEngineLabel} with the same ${dataDirectoryLabel}.`,
324
+ `The move is one-way: once ${noSqlDbEngineRelease} has written certain indexes, such as one on a field that holds lists, ` +
325
+ 'earlier gitzone releases cannot open the folder again.',
326
+ 'A copy of the folder is no way back, because the engine refuses to start on a copy, and there is no backup route yet.',
327
+ ];
328
+ };
329
+
330
+ /** Why `gitzone services upgrade mongodb` has nothing to do. */
331
+ export const describeNoSqlDbDataUpToDate = (
332
+ assessmentArg: Extract<TNoSqlDbDataAssessment, { kind: 'new' | 'current' }>,
333
+ ): string => {
334
+ if (assessmentArg.kind === 'new') {
335
+ return `Nothing to upgrade: ${dataDirectoryLabel} does not exist yet; \`gitzone services start mongo\` creates it on ${pinnedEngineLabel}.`;
336
+ }
337
+ const proof =
338
+ assessmentArg.proof === 'container' && assessmentArg.container
339
+ ? `container ${assessmentArg.container.name} runs it`
340
+ : 'its engine record says so';
341
+ return `Nothing to upgrade: ${dataDirectoryLabel} is on ${pinnedEngineLabel} (${proof}).`;
342
+ };
343
+
344
+ /**
345
+ * Record that the pinned image owns the project's data directory, unless the
346
+ * record already says so. Callers hold the project's `mongodb` data lock and
347
+ * call this only for data that is new, proven current, or being upgraded on
348
+ * request, before the first start of a pinned container on it.
349
+ */
350
+ export const ensureNoSqlDbEngineRecord = async (projectPathArg: string): Promise<void> => {
351
+ const projectPath = plugins.path.resolve(projectPathArg);
352
+ const dataPath = getServiceDataDirectory(projectPath, 'mongodb');
353
+ const dataDirectory = await readNoSqlDbDataIdentity(dataPath);
354
+ if (!dataDirectory) {
355
+ throw new Error(`Cannot record the NoSQLDB engine of a missing data directory: ${dataPath}`);
356
+ }
357
+ const existing = await readNoSqlDbEngineRecord(projectPath);
358
+ if (
359
+ noSqlDbEngineRecordProvesDirectory(existing, { projectPath, dataPath, dataDirectory }) &&
360
+ existing.image === noSqlDbImage
361
+ ) {
362
+ return;
363
+ }
364
+ const record: INoSqlDbEngineRecord = {
365
+ owner: serviceDataOwner,
366
+ kind: 'nosqldb-engine',
367
+ projectPath,
368
+ dataPath,
369
+ dataDirectory,
370
+ image: noSqlDbImage,
371
+ recordedAt: new Date().toISOString(),
372
+ };
373
+ await writeJsonFileAtomically(
374
+ getNoSqlDbEngineRecordPath(projectPath),
375
+ record,
376
+ 'NoSQLDB engine record',
377
+ );
378
+ };
@@ -19,11 +19,13 @@ export const objectStorageImage =
19
19
 
20
20
  /**
21
21
  * NoSQLDB engine image serving the `mongodb` service:
22
- * `code.foss.global/lossless.zone/database` 2.0.0 (@lossless.org/nosqldb
23
- * 10.7.3), multi-arch index digest for linux/amd64 and linux/arm64.
22
+ * `code.foss.global/lossless.zone/database` 4.0.0 (@lossless.org/nosqldb
23
+ * 10.10.0). The digest is the multi-arch index for linux/amd64 and
24
+ * linux/arm64, never a platform manifest, so Docker picks the host's platform.
25
+ * Its image contract is `noSqlDbExpected*` in `classes.servicemanager.ts`.
24
26
  */
25
27
  export const noSqlDbImage =
26
- 'code.foss.global/lossless.zone/database@sha256:8fed3bc2da051a6ce29906383ea37e3ae777e2a7373869effbd3093fc4a2a650';
28
+ 'code.foss.global/lossless.zone/database@sha256:e5a3d3243c7b43fe42607210656b49a0296f84015ba26616fca2b0b3ff4dd2e0';
27
29
 
28
30
  /** The only image older GitZone releases ever ran the `mongodb` service with. */
29
31
  export const legacyMongoImage = 'mongo:7.0';
@@ -54,9 +56,10 @@ export const serviceDataDirectoryNames: { [key in TServiceName]: string } = {
54
56
  };
55
57
 
56
58
  /**
57
- * Image used to run each service, and therefore the image available to perform
58
- * a root-helper cleanup of that service's data directory: if the data exists,
59
- * the service ran, so its image is present locally.
59
+ * Image used to run each service, and the image that performs a root-helper
60
+ * cleanup of that service's data directory. The cleanup pulls it when it is
61
+ * missing locally, since the data may have been written by a container that
62
+ * ran another version of the image.
60
63
  */
61
64
  export const serviceImages: { [key in TServiceName]: string } = {
62
65
  mongodb: noSqlDbImage,
@@ -245,29 +248,44 @@ export const isValidServiceDataMarker = (markerArg: unknown): markerArg is IServ
245
248
  return true;
246
249
  };
247
250
 
248
- const writeServiceDataMarker = async (
249
- projectPathArg: string,
250
- markerArg: IServiceDataMarker,
251
+ /**
252
+ * Write a JSON file through a fresh temporary sibling and a rename, so a
253
+ * reader sees either the previous file or the complete new one.
254
+ */
255
+ export const writeJsonFileAtomically = async (
256
+ filePathArg: string,
257
+ valueArg: unknown,
258
+ descriptionArg: string,
251
259
  ): Promise<void> => {
252
- const markerPath = getServiceDataMarkerPath(projectPathArg);
253
- await plugins.smartfs.directory(plugins.path.dirname(markerPath)).recursive().create();
254
- const tempPath = `${markerPath}.tmp-${process.pid}-${plugins.crypto
260
+ await plugins.smartfs.directory(plugins.path.dirname(filePathArg)).recursive().create();
261
+ const tempPath = `${filePathArg}.tmp-${process.pid}-${plugins.crypto
255
262
  .randomBytes(12)
256
263
  .toString('hex')}`;
257
264
  try {
258
- await plugins.fs.writeFile(tempPath, `${JSON.stringify(markerArg, null, 2)}\n`, {
265
+ await plugins.fs.writeFile(tempPath, `${JSON.stringify(valueArg, null, 2)}\n`, {
259
266
  encoding: 'utf8',
260
267
  flag: 'wx',
261
268
  });
262
- await plugins.fs.rename(tempPath, markerPath);
269
+ await plugins.fs.rename(tempPath, filePathArg);
263
270
  } catch (error) {
264
271
  await plugins.fs.rm(tempPath, { force: true }).catch(() => {});
265
- throw new Error(`Could not persist service data marker atomically: ${markerPath}`, {
272
+ throw new Error(`Could not persist ${descriptionArg} atomically: ${filePathArg}`, {
266
273
  cause: error,
267
274
  });
268
275
  }
269
276
  };
270
277
 
278
+ const writeServiceDataMarker = async (
279
+ projectPathArg: string,
280
+ markerArg: IServiceDataMarker,
281
+ ): Promise<void> => {
282
+ await writeJsonFileAtomically(
283
+ getServiceDataMarkerPath(projectPathArg),
284
+ markerArg,
285
+ 'service data marker',
286
+ );
287
+ };
288
+
271
289
  /** Read and validate the marker for a project, or undefined when absent/invalid. */
272
290
  export const readServiceDataMarker = async (
273
291
  projectPathArg: string,