feat(dashmate): record why certificate renewal failed so doctor can name the cause

packages/dashmate/src/commands/update.js

@@ -67,6 +67,7 @@ export default class UpdateCommand extends ConfigBaseCommand {
     checkGatewayCertificate,
     gatewayCertificateTask,
     dockerCompose,
+    renewalRecordRepository,
   ) {
     const {
       format,
@@ -85,6 +86,7 @@ export default class UpdateCommand extends ConfigBaseCommand {
       config,
       verdict,
       dockerCompose,
+      renewalRecordRepository,
       pull: this.pullResult ?? null,
       obtainAttemptFailed,
     });

packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js

@@ -11,6 +11,7 @@ import ConfigFileNotFoundError from '../errors/ConfigFileNotFoundError.js';
 import InvalidConfigFileFormatError from '../errors/InvalidConfigFileFormatError.js';
 import configFileJsonSchema from './configFileJsonSchema.js';
 import ConfigFile from './ConfigFile.js';
+import ConfigurationLockLostError from '../../ssl/errors/ConfigurationLockLostError.js';
 
 /**
  * How long a lock may go un-refreshed before another process may break it.
@@ -229,7 +230,7 @@ export default class ConfigFileJsonRepository {
       this.#save(configFile);
 
       if (!this.isExclusive()) {
-        throw new Error('Lost the configuration lock after saving the config file;'
+        throw new ConfigurationLockLostError('Lost the configuration lock after saving the config file;'
           + ' follow-up filesystem changes were not run. Re-run the command.');
       }
 
@@ -274,7 +275,7 @@ export default class ConfigFileJsonRepository {
 
     return this.#locked(() => {
       if (!this.isExclusive()) {
-        throw new Error('Lost the configuration lock before the config file was migrated.');
+        throw new ConfigurationLockLostError('Lost the configuration lock before the config file was migrated.');
       }
 
       // Another process may have migrated or changed the file while this
@@ -535,7 +536,7 @@ export default class ConfigFileJsonRepository {
         }
 
         if (Date.now() >= deadline) {
-          throw new Error(`Timed out waiting for configuration lock '${this.lockFilePath}'.`
+          throw new ConfigurationLockLostError(`Timed out waiting for configuration lock '${this.lockFilePath}'.`
             + ' It may be held by a Dashmate command, the dashmate helper during certificate'
             + ' renewal, or a running reindex. An abandoned lock after SIGKILL or power loss'
             + ' clears itself after about a minute; do not remove it manually while another'

packages/dashmate/src/createDIContainer.js

@@ -14,6 +14,7 @@ import getServiceListFactory from './docker/getServiceListFactory.js';
 import ensureFileMountExistsFactory from './docker/ensureFileMountExistsFactory.js';
 import getConnectionHostFactory from './docker/getConnectionHostFactory.js';
 import ConfigFileJsonRepository from './config/configFile/ConfigFileJsonRepository.js';
+import RenewalRecordRepository from './ssl/renewalRecord/RenewalRecordRepository.js';
 import createConfigFileFactory from './config/configFile/createConfigFileFactory.js';
 import migrateConfigFileFactory from './config/configFile/migrateConfigFileFactory.js';
 import DefaultConfigs from './config/DefaultConfigs.js';
@@ -166,6 +167,7 @@ export default async function createDIContainer(options = {}) {
     legoCaCertificatePath: asValue(null),
     legoContainerOptions: asValue({}),
     configFileRepository: asClass(ConfigFileJsonRepository).singleton(),
+    renewalRecordRepository: asClass(RenewalRecordRepository).singleton(),
     getBaseConfig: asFunction(getBaseConfigFactory).singleton(),
     getLocalConfig: asFunction(getLocalConfigFactory).singleton(),
     getTestnetConfig: asFunction(getTestnetConfigFactory).singleton(),

packages/dashmate/src/docsLinks.js

@@ -0,0 +1,34 @@
+/**
+ * Every documentation link dashmate prints, in one place.
+ *
+ * Gathered because they were repeated inline: the SSL-certificates anchor
+ * appeared three times in one file alone, and the certificate troubleshooting
+ * article was a constant in another. A link that lives in several places is one
+ * that gets updated in some of them - and dashmate has already shipped links
+ * that answered 404, which costs the command the credibility it needs at the
+ * moment an operator is following its instructions.
+ *
+ * Two forms appear here, deliberately. `docs.dash.org/<slug>` is a redirect
+ * configured in the documentation site's dashboard; those exist for some pages
+ * and not others. Where no redirect was created, the published path is used
+ * instead - it resolves today, and a link that resolves beats a shorter one
+ * that does not.
+ */
+export const DOCS_LINKS = {
+  /** Choosing and configuring a certificate provider. */
+  SSL_CERTIFICATES: 'https://docs.dash.org/en/stable/docs/user/masternodes/setup-evonode.html#ssl-certificates',
+
+  /** Why renewal fails, and what to do about each cause. */
+  CERTIFICATE_TROUBLESHOOTING: 'https://docs.dash.org/en/stable/docs/user/masternodes/troubleshooting-certificates.html',
+
+  /** Registering an evonode's collateral from Dash Core. */
+  EVONODE_COLLATERAL: 'https://docs.dash.org/evonode-setup-core-collateral',
+
+  /** Registering a masternode's collateral from Dash Core. */
+  MASTERNODE_COLLATERAL: 'https://docs.dash.org/mn-setup-core-collateral',
+
+  /** Dash Masternode Tool. */
+  DMT_SETUP: 'https://docs.dash.org/dmt-setup',
+};
+
+export default DOCS_LINKS;

packages/dashmate/src/doctor/analyse/analyseConfigFactory.js

@@ -5,6 +5,11 @@ import { ERRORS as ZEROSSL_ERRORS } from '../../ssl/zerossl/validateZeroSslCerti
 import { SEVERITY } from '../Prescription.js';
 import Problem from '../Problem.js';
 import renderConfigFlag from '../../util/renderConfigFlag.js';
+import { DOCS_LINKS } from '../../docsLinks.js';
+import { RENEWAL_RECORD_STATES } from '../../ssl/renewalRecord/RenewalRecordRepository.js';
+import RenewalRecord from '../../ssl/renewalRecord/RenewalRecord.js';
+import deriveRenewalGuidance, { SAFE_ACTION } from '../../ssl/renewalGuidance.js';
+import renderObtainCommand from '../../ssl/renderObtainCommand.js';
 
 /**
  * Whether a ZeroSSL certificate can be renewed depends on the operator's plan, which dashmate
@@ -16,6 +21,60 @@ of charge:
   {bold.cyanBright dashmate config set platform.gateway.ssl.providerConfigs.letsencrypt.email EMAIL}
   {bold.cyanBright dashmate ssl obtain}`;
 
+/**
+ * What to say instead of a certificate request, when the renewal record forbids
+ * one - or nothing, when it does not.
+ *
+ * The legacy checks below cannot be left to decide this for themselves. They
+ * predate the record entirely, and each one ends in its own command.
+ *
+ * @param {Samples} samples
+ * @param {Config} config
+ * @return {string|null}
+ */
+function withheldRequest(samples, config) {
+  const sample = samples.getServiceInfo('gateway', 'certificateRenewal');
+  const record = sample?.state === RENEWAL_RECORD_STATES.PRESENT
+    ? RenewalRecord.fromObject(sample)
+    : null;
+
+  // A record left by a provider this node no longer uses says nothing about the
+  // one it does. The configuration watcher hands over without clearing it, so
+  // without this a stale spent or uncertain record would suppress a request
+  // that is now perfectly valid - the renewal-aware analyser already ignores it
+  // for exactly that reason, and these two must not disagree.
+  // The same two inputs the renewal-aware analyser uses. Without the installed
+  // certificate's date, a failure that a newer certificate has already overtaken
+  // still counts here - so this analyser would replace a valid repair with stale
+  // no-obtain guidance while the other one correctly ignored the same record.
+  const applicable = record?.isFailed()
+    && record.appliesTo({
+      provider: config.get('platform.gateway.ssl.provider'),
+      certificateValidFrom: samples.getServiceInfo('gateway', 'installedCertificate')?.validFrom
+        ?? null,
+    })
+    ? record
+    : null;
+
+  const guidance = deriveRenewalGuidance({
+    record: applicable,
+    isRecordUnreadable: sample?.state === RENEWAL_RECORD_STATES.UNREADABLE
+      || (sample?.state === RENEWAL_RECORD_STATES.PRESENT && record === null),
+    isCertificateUsable: false,
+  });
+
+  // A provider switch forbids these remedies just as firmly as an outright
+  // refusal: they ask this provider for another certificate, while the
+  // renewal-aware analyser in the same report says this provider will never
+  // issue one again.
+  if (guidance.safeAction !== SAFE_ACTION.DO_NOT_OBTAIN
+    && guidance.safeAction !== SAFE_ACTION.SWITCH_PROVIDER) {
+    return null;
+  }
+
+  return renderObtainCommand({ configName: config.getName(), guidance });
+}
+
 export default function analyseConfigFactory() {
   /**
    * @typedef analyseConfig
@@ -52,7 +111,7 @@ export default function analyseConfigFactory() {
             if (config.get('network') !== NETWORK_LOCAL) {
               const problem = new Problem(
                 'SSL certificates are disabled. Clients won\'t be able to connect securely',
-                chalk`Please enable and set up SSL certificates {bold.cyanBright https://docs.dash.org/en/stable/masternodes/dashmate.html#ssl-certificate}`,
+                chalk`Please enable and set up SSL certificates {bold.cyanBright ${DOCS_LINKS.SSL_CERTIFICATES}}`,
                 SEVERITY.HIGH,
               );
 
@@ -63,7 +122,7 @@ export default function analyseConfigFactory() {
             if (config.get('network') === NETWORK_MAINNET) {
               const problem = new Problem(
                 'Self-signed SSL certificate is used on mainnet. Clients won\'t be able to connect securely',
-                chalk`Please use valid SSL certificates {bold.cyanBright https://docs.dash.org/en/stable/masternodes/dashmate.html#ssl-certificate}`,
+                chalk`Please use valid SSL certificates {bold.cyanBright ${DOCS_LINKS.SSL_CERTIFICATES}}`,
                 SEVERITY.HIGH,
               );
 
@@ -88,7 +147,7 @@ Private key file path: {bold.cyanBright ${ssl?.data?.privateFilePath}}`,
 Certificate chain file path: {bold.cyanBright ${ssl?.data?.chainFilePath}}
 Private key file path: {bold.cyanBright ${ssl?.data?.privateFilePath}}
 
-Or use ZeroSSL https://docs.dash.org/en/stable/masternodes/dashmate.html#ssl-certificate`,
+Or use ZeroSSL ${DOCS_LINKS.SSL_CERTIFICATES}`,
               },
             };
 
@@ -211,9 +270,14 @@ a working certificate.`,
             }[ssl.error] ?? {};
 
             if (description) {
+              // These checks predate the renewal record and each ends in its
+              // own request. They run before the renewal-aware analyser in the
+              // same report, so a node whose recorded cause forbids asking
+              // again would read "do not obtain" from one and a runnable
+              // command from the other - and follow the command.
               const problem = new Problem(
                 description,
-                solution,
+                withheldRequest(samples, config) ?? solution,
                 severity,
               );