@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.
@@ -29,6 +29,16 @@ import {
29
29
  type TServiceName,
30
30
  } from './classes.servicedatamarker.js';
31
31
  import { readPersistedServiceConfiguration } from './classes.servicenames.js';
32
+ import {
33
+ classifyNoSqlDbData,
34
+ ensureNoSqlDbEngineRecord,
35
+ getNoSqlDbDataRefusal,
36
+ noSqlDbDataNeedsUpgrade,
37
+ readNoSqlDbDataIdentity,
38
+ readNoSqlDbEngineRecord,
39
+ sameNoSqlDbDataAssessment,
40
+ type TNoSqlDbDataAssessment,
41
+ } from './classes.nosqldbengine.js';
32
42
  import { withServiceDataOperationLock } from './classes.interprocesslock.js';
33
43
  import {
34
44
  LegacyMongoMigration,
@@ -80,7 +90,8 @@ export type TServiceManagerOperation =
80
90
  | 'restart'
81
91
  | 'start'
82
92
  | 'status'
83
- | 'stop';
93
+ | 'stop'
94
+ | 'upgrade';
84
95
 
85
96
  export const getServiceManagerMigrationScopes = (
86
97
  operationArg: TServiceManagerOperation,
@@ -88,7 +99,7 @@ export const getServiceManagerMigrationScopes = (
88
99
  'global-registry',
89
100
  'service-selection',
90
101
  'runtime-config',
91
- ...(['start', 'restart', 'reconfigure', 'clean', 'migrate'].includes(operationArg)
102
+ ...(['start', 'restart', 'reconfigure', 'clean', 'migrate', 'upgrade'].includes(operationArg)
92
103
  ? (['service-data-marker'] as const)
93
104
  : []),
94
105
  ];
@@ -125,14 +136,15 @@ export const noSqlDbWirePort = '27017';
125
136
  /** Management UI port inside the container; deliberately never published. */
126
137
  export const noSqlDbUiPort = '3000';
127
138
  /*
128
- * Contract of the pinned `noSqlDbImage` (lossless.zone/database 2.0.0), as
139
+ * Contract of the pinned `noSqlDbImage` (lossless.zone/database 4.0.0), as
129
140
  * reported by its image config. A created container must carry exactly these
130
141
  * values; any drift means the container was not created by this release.
131
142
  */
132
143
  /** Numeric `uid:gid` of the image's `database` user; also owns the bind-mounted data. */
133
144
  export const noSqlDbContainerUser = '999:999';
134
145
  export const noSqlDbExpectedEntrypoint = ['/sbin/tini', '--'];
135
- export const noSqlDbExpectedCommand = ['deno', 'run', '--allow-all', 'mod.ts', 'server'];
146
+ /** The image's own `Cmd`; the container is created without a command of its own. */
147
+ export const noSqlDbExpectedCommand = ['node', 'cli.js', 'server'];
136
148
  /** The image's own HEALTHCHECK, compared exactly. */
137
149
  export const noSqlDbExpectedHealthcheck = {
138
150
  test: ['CMD-SHELL', 'wget -q -O /dev/null http://127.0.0.1:3000/readyz || exit 1'],
@@ -146,6 +158,15 @@ export const noSqlDbReconciliationTimeoutMs = 60_000;
146
158
  const noSqlDbMigrationStopGraceSeconds = 60;
147
159
  /** `service`: published and auto-restarting. `migration`: unreachable restore phase. */
148
160
  type TNoSqlDbContainerShape = 'service' | 'migration';
161
+
162
+ /**
163
+ * `engineUpgrade` is passed only by `gitzone services upgrade mongodb`: it lets
164
+ * the start move data that another engine wrote, or that no evidence places,
165
+ * onto the pinned image.
166
+ */
167
+ interface INoSqlDbStartOptions {
168
+ engineUpgrade?: boolean;
169
+ }
149
170
  type THardenedService = 'mongodb' | 'objectstorage';
150
171
 
151
172
  /** Image and in-container user that own each hardened data directory. */
@@ -921,7 +942,9 @@ export class ServiceManager {
921
942
  }
922
943
  }
923
944
 
924
- private createLegacyMongoMigration(): LegacyMongoMigration {
945
+ private createLegacyMongoMigration(
946
+ optionsArg: INoSqlDbStartOptions = {},
947
+ ): LegacyMongoMigration {
925
948
  const getuid = process.getuid;
926
949
  const getgid = process.getgid;
927
950
  if (!getuid || !getgid) {
@@ -940,7 +963,7 @@ export class ServiceManager {
940
963
  this.globalRegistry.clearLegacyMongoContainer(projectPathArg, nameArg),
941
964
  startMigrationNoSqlDb: () => this.startMigrationNoSqlDbContainer(),
942
965
  stopMigrationNoSqlDb: () => this.stopMigrationNoSqlDbContainer(),
943
- publishMigratedNoSqlDb: () => this.publishMigratedNoSqlDbContainer(),
966
+ publishMigratedNoSqlDb: () => this.publishMigratedNoSqlDbContainer(optionsArg),
944
967
  log: (levelArg, messageArg) => logger.log(levelArg, messageArg),
945
968
  });
946
969
  }
@@ -969,6 +992,8 @@ export class ServiceManager {
969
992
  );
970
993
  }
971
994
  await this.prepareNoSqlDbDataDirectory(timeout);
995
+ // The restore writes into a new directory on the pin.
996
+ await ensureNoSqlDbEngineRecord(process.cwd());
972
997
  const inspection = await this.createNoSqlDbContainer(
973
998
  this.getNoSqlDbExpectedLabels(),
974
999
  timeout,
@@ -1022,12 +1047,17 @@ export class ServiceManager {
1022
1047
  * container on the same data directory and wait until it is ready.
1023
1048
  * Idempotent: once the service container exists it is only reconciled.
1024
1049
  */
1025
- private async publishMigratedNoSqlDbContainer(): Promise<{ id: string }> {
1050
+ private async publishMigratedNoSqlDbContainer(
1051
+ optionsArg: INoSqlDbStartOptions = {},
1052
+ ): Promise<{ id: string }> {
1026
1053
  const timeout = () => ({
1027
1054
  timeoutMs: (noSqlDbMigrationStopGraceSeconds + 60) * 1_000,
1028
1055
  });
1029
1056
  const restorePhase = await this.inspectMigrationNoSqlDbContainer(timeout);
1030
1057
  if (restorePhase) {
1058
+ // The restore-phase container on the pin is the only proof of its data
1059
+ // until the record exists; a migration an earlier release began has none.
1060
+ await ensureNoSqlDbEngineRecord(process.cwd());
1031
1061
  if (restorePhase.running) {
1032
1062
  await this.docker.execArgv(
1033
1063
  ['stop', '-t', String(noSqlDbMigrationStopGraceSeconds), restorePhase.id],
@@ -1038,19 +1068,19 @@ export class ServiceManager {
1038
1068
  // the image declares no other volume.
1039
1069
  await this.docker.execArgv(['rm', restorePhase.id], timeout());
1040
1070
  }
1041
- const { id } = await this.reconcileNoSqlDbContainer();
1071
+ const { id } = await this.reconcileNoSqlDbContainer(optionsArg);
1042
1072
  return { id };
1043
1073
  }
1044
1074
 
1045
- private async startMongoDBLocked(): Promise<void> {
1075
+ private async startMongoDBLocked(optionsArg: INoSqlDbStartOptions = {}): Promise<void> {
1046
1076
  await this.config.reloadFromDisk();
1047
1077
  await this.assertNoPendingDataDeletion('mongodb');
1048
1078
  await this.globalRegistry.touchProject(process.cwd());
1049
1079
  logger.log('note', '📦 MongoDB (NoSQLDB):');
1050
1080
  this.assertNoSqlDbConfigurationSafe();
1051
1081
 
1052
- await this.createLegacyMongoMigration().run();
1053
- const { outcome } = await this.reconcileNoSqlDbContainer();
1082
+ await this.createLegacyMongoMigration(optionsArg).run();
1083
+ const { outcome } = await this.reconcileNoSqlDbContainer(optionsArg);
1054
1084
 
1055
1085
  const config = this.config.getConfig();
1056
1086
  const containers = this.config.getContainerNames();
@@ -1075,6 +1105,128 @@ export class ServiceManager {
1075
1105
  }
1076
1106
  }
1077
1107
 
1108
+ /**
1109
+ * Classify which database engine wrote this project's NoSQLDB data.
1110
+ * Read-only: Docker queries by exact name and id, `lstat`, and the engine
1111
+ * record; it pulls, prepares, writes and starts nothing.
1112
+ */
1113
+ public async assessNoSqlDbData(): Promise<TNoSqlDbDataAssessment> {
1114
+ const projectPath = plugins.path.resolve(process.cwd());
1115
+ const containers = this.config.getContainerNames();
1116
+ const dataPath = plugins.path.resolve(this.config.getDataDirectories().nosqldb);
1117
+ const timeout = () => ({ timeoutMs: noSqlDbReconciliationTimeoutMs });
1118
+ await this.assertNoSymlinkedServiceDataPath('mongodb', dataPath);
1119
+ const id = await this.discoverContainerIdByExactName(containers.nosqldb, timeout);
1120
+ const inspection = id
1121
+ ? await this.revalidateNoSqlDbContainer(
1122
+ id,
1123
+ containers.nosqldb,
1124
+ this.getNoSqlDbExpectedLabels(),
1125
+ timeout,
1126
+ )
1127
+ : undefined;
1128
+ return classifyNoSqlDbData({
1129
+ projectPath,
1130
+ dataPath,
1131
+ container: inspection && {
1132
+ id: inspection.id,
1133
+ name: inspection.name,
1134
+ image: inspection.image,
1135
+ status: inspection.status,
1136
+ running: inspection.running,
1137
+ mountSources: inspection.mounts.map((mountArg) => mountArg.source),
1138
+ },
1139
+ dataDirectory: await readNoSqlDbDataIdentity(dataPath),
1140
+ record: await readNoSqlDbEngineRecord(projectPath),
1141
+ });
1142
+ }
1143
+
1144
+ /**
1145
+ * Read-only preflight used before restart or reconfigure may stop anything:
1146
+ * refuses data that another engine wrote or that no evidence places.
1147
+ */
1148
+ public async assertNoSqlDbDataStartable(): Promise<void> {
1149
+ const refusal = getNoSqlDbDataRefusal(await this.assessNoSqlDbData());
1150
+ if (refusal) {
1151
+ throw new Error(refusal);
1152
+ }
1153
+ }
1154
+
1155
+ /**
1156
+ * Move the project's NoSQLDB data onto the pinned image, the one-way step
1157
+ * `gitzone services upgrade mongodb` confirms. Refuses when the evidence
1158
+ * changed since `confirmedArg` was shown; data that needs no upgrade is
1159
+ * left alone.
1160
+ */
1161
+ public async upgradeMongoDB(confirmedArg: TNoSqlDbDataAssessment): Promise<void> {
1162
+ await withServiceDataOperationLock(process.cwd(), 'mongodb', async () => {
1163
+ await this.config.reloadFromDisk();
1164
+ await this.assertNoPendingDataDeletion('mongodb');
1165
+ await this.assertMongoStartupAllowed();
1166
+ const assessment = await this.assessNoSqlDbData();
1167
+ if (!sameNoSqlDbDataAssessment(assessment, confirmedArg)) {
1168
+ throw new Error(
1169
+ 'The NoSQLDB data or its container changed after the upgrade was confirmed; nothing was changed. ' +
1170
+ 'Run `gitzone services upgrade mongodb` again.',
1171
+ );
1172
+ }
1173
+ if (!noSqlDbDataNeedsUpgrade(assessment)) {
1174
+ return;
1175
+ }
1176
+ if (assessment.container) {
1177
+ await this.stopNoSqlDbContainerForUpgrade(assessment.container.id);
1178
+ }
1179
+ await this.startMongoDBLocked({ engineUpgrade: true });
1180
+ });
1181
+ }
1182
+
1183
+ /**
1184
+ * Stop the old engine gracefully, so it flushes before its container is
1185
+ * replaced. Runs under its own timeout, before the start-up deadline, and
1186
+ * aborts the upgrade unless the container is proven stopped.
1187
+ */
1188
+ private async stopNoSqlDbContainerForUpgrade(containerIdArg: string): Promise<void> {
1189
+ const containers = this.config.getContainerNames();
1190
+ const labels = this.getNoSqlDbExpectedLabels();
1191
+ const timeout = () => ({
1192
+ timeoutMs: (noSqlDbMigrationStopGraceSeconds + 60) * 1_000,
1193
+ });
1194
+ const inspection = await this.revalidateNoSqlDbContainer(
1195
+ containerIdArg,
1196
+ containers.nosqldb,
1197
+ labels,
1198
+ timeout,
1199
+ );
1200
+ if (!inspection.running && inspection.status !== 'restarting') {
1201
+ return;
1202
+ }
1203
+ logger.log('note', ' Stopping the old engine gracefully...');
1204
+ try {
1205
+ await this.docker.execArgv(
1206
+ ['stop', '-t', String(noSqlDbMigrationStopGraceSeconds), inspection.id],
1207
+ timeout(),
1208
+ );
1209
+ } catch (error) {
1210
+ throw new Error(
1211
+ `Could not stop NoSQLDB container ${containers.nosqldb} gracefully; ` +
1212
+ 'the upgrade removed nothing and left the folder unchanged.',
1213
+ { cause: error },
1214
+ );
1215
+ }
1216
+ const stopped = await this.revalidateNoSqlDbContainer(
1217
+ inspection.id,
1218
+ containers.nosqldb,
1219
+ labels,
1220
+ timeout,
1221
+ );
1222
+ if (stopped.running || stopped.status === 'restarting') {
1223
+ throw new Error(
1224
+ `NoSQLDB container ${containers.nosqldb} is still running after a graceful stop; ` +
1225
+ 'the upgrade removed nothing and left the folder unchanged.',
1226
+ );
1227
+ }
1228
+ }
1229
+
1078
1230
  private assertNoSqlDbConfigurationSafe(): void {
1079
1231
  this.config.assertMongoExposureIsSafe();
1080
1232
  this.config.assertNoSqlDbCredentialsAreSafe();
@@ -1278,10 +1430,23 @@ export class ServiceManager {
1278
1430
  * Create, start, or reconcile the canonical NoSQLDB container by immutable id
1279
1431
  * and wait until it answers authenticated requests. Containers started by
1280
1432
  * this invocation are stopped again when reconciliation fails.
1433
+ *
1434
+ * Data another engine wrote, or that no evidence places, is refused first,
1435
+ * before any pull, data preparation or container change; only an explicit
1436
+ * engine upgrade moves it.
1281
1437
  */
1282
- private async reconcileNoSqlDbContainer(): Promise<{ id: string; outcome: string }> {
1438
+ private async reconcileNoSqlDbContainer(
1439
+ optionsArg: INoSqlDbStartOptions = {},
1440
+ ): Promise<{ id: string; outcome: string }> {
1441
+ if (!optionsArg.engineUpgrade) {
1442
+ await this.assertNoSqlDbDataStartable();
1443
+ }
1283
1444
  const containers = this.config.getContainerNames();
1284
1445
  const directories = this.config.getDataDirectories();
1446
+ // The first start after a pin change has to pull the image. The pull has
1447
+ // its own bound; inside the deadline, the data helper or `docker create`
1448
+ // would pull it on demand and spend the readiness window on the download.
1449
+ await this.docker.ensureImagePresent(noSqlDbImage);
1285
1450
  const deadlineAt = this.noSqlDbClock.now() + noSqlDbReconciliationTimeoutMs;
1286
1451
  const dockerTimeout = (): { timeoutMs: number } => {
1287
1452
  const remaining = Math.floor(deadlineAt - this.noSqlDbClock.now());
@@ -1346,6 +1511,7 @@ export class ServiceManager {
1346
1511
  let outcome: string;
1347
1512
  if (!initialInspection || needsRecreate) {
1348
1513
  await this.prepareNoSqlDbDataDirectory(dockerTimeout);
1514
+ await ensureNoSqlDbEngineRecord(process.cwd());
1349
1515
  if (initialInspection) {
1350
1516
  logger.log('note', ' Runtime configuration changed, recreating container...');
1351
1517
  await this.revalidateNoSqlDbContainer(
@@ -1365,11 +1531,14 @@ export class ServiceManager {
1365
1531
  : 'Created, started, and ready';
1366
1532
  } else if (!initialInspection.running) {
1367
1533
  await this.prepareNoSqlDbDataDirectory(dockerTimeout);
1534
+ await ensureNoSqlDbEngineRecord(process.cwd());
1368
1535
  logger.log('note', ' Starting existing container...');
1369
1536
  activeInspection = initialInspection;
1370
1537
  await startById(activeInspection.id, false);
1371
1538
  outcome = 'Started and ready';
1372
1539
  } else {
1540
+ // The running container proves the data; record it for when it is gone.
1541
+ await ensureNoSqlDbEngineRecord(process.cwd());
1373
1542
  activeInspection = initialInspection;
1374
1543
  outcome = 'Already running and ready';
1375
1544
  }
@@ -3086,6 +3255,10 @@ export class ServiceManager {
3086
3255
  await this.config.reloadFromDisk();
3087
3256
  await this.assertNoLegacyMinioResources(() => ({ timeoutMs: 60_000 }));
3088
3257
  await this.assertMongoStartupAllowed();
3258
+ if (this.isServiceEnabled('mongodb')) {
3259
+ // The restart that follows would refuse this data after the stop.
3260
+ await this.assertNoSqlDbDataStartable();
3261
+ }
3089
3262
 
3090
3263
  // Stop existing containers
3091
3264
  logger.log('note', '🛑 Stopping existing containers...');
@@ -3,6 +3,11 @@ import * as helpers from "./helpers.js";
3
3
  import { ServiceManager } from "./classes.servicemanager.js";
4
4
  import { GlobalRegistry } from "./classes.globalregistry.js";
5
5
  import { getServiceDataDirectory } from "./classes.servicedatamarker.js";
6
+ import {
7
+ describeNoSqlDbDataUpToDate,
8
+ describeNoSqlDbUpgrade,
9
+ noSqlDbDataNeedsUpgrade,
10
+ } from "./classes.nosqldbengine.js";
6
11
  import { serviceSecretEnvironmentNames } from "./classes.serviceconfiguration.js";
7
12
  import {
8
13
  allowedServiceNames,
@@ -109,6 +114,7 @@ export const run = async (argvArg: any) => {
109
114
  case "compass":
110
115
  case "logs":
111
116
  case "migrate":
117
+ case "upgrade":
112
118
  case "remove":
113
119
  case "clean":
114
120
  case "reconfigure": {
@@ -164,6 +170,10 @@ export const run = async (argvArg: any) => {
164
170
  case "migrate":
165
171
  await handleMigrate(serviceManager, argvArg._[2], mode);
166
172
  break;
173
+
174
+ case "upgrade":
175
+ await handleUpgrade(serviceManager, argvArg._[2], mode);
176
+ break;
167
177
  }
168
178
  break;
169
179
  }
@@ -503,6 +513,7 @@ export async function handleRestart(serviceManager: ServiceManager, service: str
503
513
  case "mongo":
504
514
  case "mongodb":
505
515
  await serviceManager.assertMongoStartupAllowed();
516
+ await serviceManager.assertNoSqlDbDataStartable();
506
517
  await serviceManager.stopMongoDB();
507
518
  await plugins.smartpromise.delayFor(2000);
508
519
  await serviceManager.startMongoDB();
@@ -530,6 +541,7 @@ export async function handleRestart(serviceManager: ServiceManager, service: str
530
541
  case "":
531
542
  if (serviceManager.isServiceEnabled("mongodb")) {
532
543
  await serviceManager.assertMongoStartupAllowed();
544
+ await serviceManager.assertNoSqlDbDataStartable();
533
545
  }
534
546
  if (serviceManager.isServiceEnabled("objectstorage")) {
535
547
  await serviceManager.assertObjectStorageStartupAllowed();
@@ -584,6 +596,44 @@ async function handleMigrate(
584
596
  await serviceManager.registerWithGlobalRegistry();
585
597
  }
586
598
 
599
+ /**
600
+ * Move NoSQLDB data that another database engine wrote, or that gitzone
601
+ * cannot place, onto the pinned engine. `start`, `restart` and `reconfigure`
602
+ * refuse such data; this command moves it, one-way, after confirmation.
603
+ */
604
+ export async function handleUpgrade(
605
+ serviceManager: ServiceManager,
606
+ rawService: string | undefined,
607
+ mode: ICliMode,
608
+ ) {
609
+ if (rawService !== "mongodb" && rawService !== "mongo") {
610
+ throw new Error("Usage: gitzone services upgrade mongodb [--yes]");
611
+ }
612
+ helpers.printHeader("Upgrading MongoDB (NoSQLDB) data");
613
+ const assessment = await serviceManager.assessNoSqlDbData();
614
+ if (!noSqlDbDataNeedsUpgrade(assessment)) {
615
+ logger.log("ok", describeNoSqlDbDataUpToDate(assessment));
616
+ return;
617
+ }
618
+ for (const line of describeNoSqlDbUpgrade(assessment)) {
619
+ logger.log("note", line);
620
+ }
621
+ if (!mode.yes) {
622
+ if (!mode.interactive) {
623
+ throw new Error(
624
+ "`services upgrade` moves the database one-way. Re-run with --yes to confirm non-interactively.",
625
+ );
626
+ }
627
+ const upgradeNow = await confirm("Upgrade now?", false);
628
+ if (!upgradeNow) {
629
+ logger.log("note", "Cancelled");
630
+ return;
631
+ }
632
+ }
633
+ await serviceManager.upgradeMongoDB(assessment);
634
+ await serviceManager.registerWithGlobalRegistry();
635
+ }
636
+
587
637
  async function handleRemove(serviceManager: ServiceManager, mode: ICliMode) {
588
638
  helpers.printHeader("Removing Containers");
589
639
  logger.log("note", "⚠️ This will remove containers but preserve data");
@@ -887,6 +937,11 @@ export function showHelp(mode?: ICliMode) {
887
937
  description:
888
938
  "Migrate legacy mongod data into NoSQLDB (start does this automatically); --yes skips the prompt",
889
939
  },
940
+ {
941
+ name: "upgrade mongodb",
942
+ description:
943
+ "Move NoSQLDB data another database engine wrote onto the pinned engine (one-way); --yes skips the prompt",
944
+ },
890
945
  {
891
946
  name: "prune",
892
947
  description:
@@ -953,6 +1008,10 @@ export function showHelp(mode?: ICliMode) {
953
1008
  "info",
954
1009
  " migrate mongodb Migrate legacy mongod data into NoSQLDB [--yes]",
955
1010
  );
1011
+ logger.log(
1012
+ "info",
1013
+ " upgrade mongodb Move NoSQLDB data onto the pinned engine (one-way) [--yes]",
1014
+ );
956
1015
  logger.log(
957
1016
  "info",
958
1017
  " prune Report reclaimable data/containers machine-wide",