@git.zone/cli 12.0.0 → 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
  ];
@@ -147,6 +158,15 @@ export const noSqlDbReconciliationTimeoutMs = 60_000;
147
158
  const noSqlDbMigrationStopGraceSeconds = 60;
148
159
  /** `service`: published and auto-restarting. `migration`: unreachable restore phase. */
149
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
+ }
150
170
  type THardenedService = 'mongodb' | 'objectstorage';
151
171
 
152
172
  /** Image and in-container user that own each hardened data directory. */
@@ -922,7 +942,9 @@ export class ServiceManager {
922
942
  }
923
943
  }
924
944
 
925
- private createLegacyMongoMigration(): LegacyMongoMigration {
945
+ private createLegacyMongoMigration(
946
+ optionsArg: INoSqlDbStartOptions = {},
947
+ ): LegacyMongoMigration {
926
948
  const getuid = process.getuid;
927
949
  const getgid = process.getgid;
928
950
  if (!getuid || !getgid) {
@@ -941,7 +963,7 @@ export class ServiceManager {
941
963
  this.globalRegistry.clearLegacyMongoContainer(projectPathArg, nameArg),
942
964
  startMigrationNoSqlDb: () => this.startMigrationNoSqlDbContainer(),
943
965
  stopMigrationNoSqlDb: () => this.stopMigrationNoSqlDbContainer(),
944
- publishMigratedNoSqlDb: () => this.publishMigratedNoSqlDbContainer(),
966
+ publishMigratedNoSqlDb: () => this.publishMigratedNoSqlDbContainer(optionsArg),
945
967
  log: (levelArg, messageArg) => logger.log(levelArg, messageArg),
946
968
  });
947
969
  }
@@ -970,6 +992,8 @@ export class ServiceManager {
970
992
  );
971
993
  }
972
994
  await this.prepareNoSqlDbDataDirectory(timeout);
995
+ // The restore writes into a new directory on the pin.
996
+ await ensureNoSqlDbEngineRecord(process.cwd());
973
997
  const inspection = await this.createNoSqlDbContainer(
974
998
  this.getNoSqlDbExpectedLabels(),
975
999
  timeout,
@@ -1023,12 +1047,17 @@ export class ServiceManager {
1023
1047
  * container on the same data directory and wait until it is ready.
1024
1048
  * Idempotent: once the service container exists it is only reconciled.
1025
1049
  */
1026
- private async publishMigratedNoSqlDbContainer(): Promise<{ id: string }> {
1050
+ private async publishMigratedNoSqlDbContainer(
1051
+ optionsArg: INoSqlDbStartOptions = {},
1052
+ ): Promise<{ id: string }> {
1027
1053
  const timeout = () => ({
1028
1054
  timeoutMs: (noSqlDbMigrationStopGraceSeconds + 60) * 1_000,
1029
1055
  });
1030
1056
  const restorePhase = await this.inspectMigrationNoSqlDbContainer(timeout);
1031
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());
1032
1061
  if (restorePhase.running) {
1033
1062
  await this.docker.execArgv(
1034
1063
  ['stop', '-t', String(noSqlDbMigrationStopGraceSeconds), restorePhase.id],
@@ -1039,19 +1068,19 @@ export class ServiceManager {
1039
1068
  // the image declares no other volume.
1040
1069
  await this.docker.execArgv(['rm', restorePhase.id], timeout());
1041
1070
  }
1042
- const { id } = await this.reconcileNoSqlDbContainer();
1071
+ const { id } = await this.reconcileNoSqlDbContainer(optionsArg);
1043
1072
  return { id };
1044
1073
  }
1045
1074
 
1046
- private async startMongoDBLocked(): Promise<void> {
1075
+ private async startMongoDBLocked(optionsArg: INoSqlDbStartOptions = {}): Promise<void> {
1047
1076
  await this.config.reloadFromDisk();
1048
1077
  await this.assertNoPendingDataDeletion('mongodb');
1049
1078
  await this.globalRegistry.touchProject(process.cwd());
1050
1079
  logger.log('note', '📦 MongoDB (NoSQLDB):');
1051
1080
  this.assertNoSqlDbConfigurationSafe();
1052
1081
 
1053
- await this.createLegacyMongoMigration().run();
1054
- const { outcome } = await this.reconcileNoSqlDbContainer();
1082
+ await this.createLegacyMongoMigration(optionsArg).run();
1083
+ const { outcome } = await this.reconcileNoSqlDbContainer(optionsArg);
1055
1084
 
1056
1085
  const config = this.config.getConfig();
1057
1086
  const containers = this.config.getContainerNames();
@@ -1076,6 +1105,128 @@ export class ServiceManager {
1076
1105
  }
1077
1106
  }
1078
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
+
1079
1230
  private assertNoSqlDbConfigurationSafe(): void {
1080
1231
  this.config.assertMongoExposureIsSafe();
1081
1232
  this.config.assertNoSqlDbCredentialsAreSafe();
@@ -1279,8 +1430,17 @@ export class ServiceManager {
1279
1430
  * Create, start, or reconcile the canonical NoSQLDB container by immutable id
1280
1431
  * and wait until it answers authenticated requests. Containers started by
1281
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.
1282
1437
  */
1283
- 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
+ }
1284
1444
  const containers = this.config.getContainerNames();
1285
1445
  const directories = this.config.getDataDirectories();
1286
1446
  // The first start after a pin change has to pull the image. The pull has
@@ -1351,6 +1511,7 @@ export class ServiceManager {
1351
1511
  let outcome: string;
1352
1512
  if (!initialInspection || needsRecreate) {
1353
1513
  await this.prepareNoSqlDbDataDirectory(dockerTimeout);
1514
+ await ensureNoSqlDbEngineRecord(process.cwd());
1354
1515
  if (initialInspection) {
1355
1516
  logger.log('note', ' Runtime configuration changed, recreating container...');
1356
1517
  await this.revalidateNoSqlDbContainer(
@@ -1370,11 +1531,14 @@ export class ServiceManager {
1370
1531
  : 'Created, started, and ready';
1371
1532
  } else if (!initialInspection.running) {
1372
1533
  await this.prepareNoSqlDbDataDirectory(dockerTimeout);
1534
+ await ensureNoSqlDbEngineRecord(process.cwd());
1373
1535
  logger.log('note', ' Starting existing container...');
1374
1536
  activeInspection = initialInspection;
1375
1537
  await startById(activeInspection.id, false);
1376
1538
  outcome = 'Started and ready';
1377
1539
  } else {
1540
+ // The running container proves the data; record it for when it is gone.
1541
+ await ensureNoSqlDbEngineRecord(process.cwd());
1378
1542
  activeInspection = initialInspection;
1379
1543
  outcome = 'Already running and ready';
1380
1544
  }
@@ -3091,6 +3255,10 @@ export class ServiceManager {
3091
3255
  await this.config.reloadFromDisk();
3092
3256
  await this.assertNoLegacyMinioResources(() => ({ timeoutMs: 60_000 }));
3093
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
+ }
3094
3262
 
3095
3263
  // Stop existing containers
3096
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",