@oneuptime/common 12.0.2 → 12.0.4

package/Server/Services/DatabaseService.ts

@@ -30,6 +30,7 @@ import UpdateByID from "../Types/Database/UpdateByID";
 import UpdateByIDAndFetch from "../Types/Database/UpdateByIDAndFetch";
 import UpdateOneBy from "../Types/Database/UpdateOneBy";
 import Encryption from "../Utils/Encryption";
+import PasswordHash from "../Utils/PasswordHash";
 import PostgresErrorTranslator from "../Utils/Database/PostgresErrorTranslator";
 import logger, { LogAttributes } from "../Utils/Logger";
 import BaseService from "./BaseService";
@@ -321,6 +322,55 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
     return data;
   }
 
+  /*
+   * Hash one HashedString column in place.
+   *
+   * Declaring `hashSaltColumn` on a column is what marks it a CREDENTIAL —
+   * a low-entropy, human-chosen secret. Those go through scrypt (see
+   * PasswordHash): deliberately slow and memory-hard, with a fresh per-record
+   * salt minted into the sibling column named by the metadata.
+   *
+   * Columns without a salt column are high-entropy values the server itself
+   * generated — session refresh tokens and the like. They keep the fast
+   * SHA-256 hash, which is the right tool for them: there is nothing to guess,
+   * and they have to stay searchable by hash because that is how they are
+   * looked up.
+   *
+   * The salt is written onto the SAME payload as the hash, so the pair can
+   * never be persisted out of step with each other.
+   *
+   * The salt column grants nobody create or update rights, so it has to get
+   * past the column-permission check some other way on each path. On update
+   * it does so by timing — sanitizeCreateOrUpdate runs after the check. On
+   * create the check runs after `hash()`, so the salt column relies on being
+   * declared `computed: true`, which checkDataColumnPermissions skips on
+   * create. A salt column that forgets that flag breaks every non-root
+   * create of a row carrying a password.
+   */
+  private async hashColumnValue(data: {
+    payload: TBaseModel | PartialEntity<TBaseModel>;
+    columnName: string;
+    columnValue: HashedString;
+  }): Promise<void> {
+    const saltColumnName: string | undefined =
+      this.model.getTableColumnMetadata(data.columnName)?.hashSaltColumn;
+
+    if (!saltColumnName) {
+      await data.columnValue.hashValue(EncryptionSecret);
+      return;
+    }
+
+    const salt: string = PasswordHash.generateSalt();
+    (data.payload as any)[saltColumnName] = salt;
+
+    data.columnValue.setHashedValue(
+      await PasswordHash.hash({
+        plainValue: data.columnValue.toString(),
+        salt: salt,
+      }),
+    );
+  }
+
   protected async hash(data: TBaseModel): Promise<TBaseModel> {
     const columns: Columns = data.getHashedColumns();
 
@@ -329,13 +379,110 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
         data.hasValue(key) &&
         !(data.getValue(key) as HashedString).isValueHashed()
       ) {
-        await ((data as any)[key] as HashedString).hashValue(EncryptionSecret);
+        await this.hashColumnValue({
+          payload: data,
+          columnName: key,
+          columnValue: (data as any)[key] as HashedString,
+        });
       }
     }
 
     return data;
   }
 
+  /*
+   * Check a plaintext secret (a password) against a hashed column on a row
+   * that has already been read out of the database, and re-hash the stored
+   * value in place when it was not written by today's scheme.
+   *
+   * The row must have been selected with BOTH the hashed column and its salt
+   * column. Without the salt a scrypt hash cannot be checked at all, and an
+   * older SHA-256 one would be checked against the wrong scheme — either way
+   * a perfectly good password gets rejected. PasswordHash.verify throws
+   * rather than silently returning false for the scrypt case, because a
+   * missing SELECT is a bug and must not look like a bad password.
+   *
+   * Why the caller cannot just query by the hash any more: with a per-user
+   * salt the hash is not computable until the row's own salt is known, so
+   * `WHERE password = <hash>` has nothing to bind. Read the row by its
+   * identity (email, id) and verify here.
+   *
+   * THE UPGRADE. Anything that is not exactly what PasswordHash writes today
+   * is re-hashed once the password is known to be correct: the two SHA-256
+   * schemes that preceded scrypt, and any scrypt hash whose cost parameters
+   * have since been raised. That is what makes raising the cost a one-line
+   * change — users migrate as they log in, with no reset and no migration.
+   *
+   * The write is deliberately hook-free and leaves updatedAt alone: the user
+   * did not change their password, the server changed how it stores it.
+   * Firing the password-change hooks would revoke every session and mail the
+   * user about a change they did not make. A failed upgrade is logged and
+   * swallowed — a correct password must not be rejected because a
+   * bookkeeping write lost a race.
+   */
+  @CaptureSpan()
+  public async verifyHashedColumnValue(data: {
+    item: TBaseModel;
+    columnName: string;
+    plainValue: string;
+  }): Promise<boolean> {
+    const storedHash: string | undefined = (data.item as any)[
+      data.columnName
+    ]?.toString();
+
+    if (!storedHash || !data.plainValue) {
+      return false;
+    }
+
+    const saltColumnName: string | undefined =
+      this.model.getTableColumnMetadata(data.columnName)?.hashSaltColumn;
+
+    const salt: string | null = saltColumnName
+      ? ((data.item as any)[saltColumnName] as string | undefined) || null
+      : null;
+
+    const isValid: boolean = await PasswordHash.verify({
+      plainValue: data.plainValue,
+      storedValue: storedHash,
+      salt: salt,
+    });
+
+    if (!isValid) {
+      return false;
+    }
+
+    if (
+      saltColumnName &&
+      data.item.id &&
+      PasswordHash.needsUpgrade(storedHash)
+    ) {
+      try {
+        const newSalt: string = PasswordHash.generateSalt();
+
+        await this.updateColumnsByIdWithoutHooks({
+          id: data.item.id,
+          data: {
+            [data.columnName]: await PasswordHash.hash({
+              plainValue: data.plainValue,
+              salt: newSalt,
+            }),
+            [saltColumnName]: newSalt,
+          } as unknown as PartialEntity<TBaseModel>,
+          skipUpdateDateColumn: true,
+        });
+      } catch (err) {
+        /*
+         * `data.item` is deliberately left holding the old hash and old salt,
+         * so it stays an internally consistent pair whether or not the write
+         * above landed.
+         */
+        logger.error(err);
+      }
+    }
+
+    return true;
+  }
+
   protected async decrypt(data: TBaseModel): Promise<TBaseModel> {
     for (const key of data.getEncryptedColumns().columns) {
       if (!data.hasValue(key)) {
@@ -552,6 +699,26 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
       if (this.model.isHashedStringColumn(columnName)) {
         const columnValue: JSONValue = (data as any)[columnName];
 
+        /*
+         * A salted column's hash and its salt are only ever correct as a
+         * pair. A write that supplies the column as a bare string skips the
+         * hashing branch below, leaving the row's existing salt attached to
+         * a value it was not computed from — which locks the account out
+         * silently, at the next login, far from whatever wrote it. Refuse
+         * instead. Callers pass a HashedString; the write path hashes it.
+         */
+        if (
+          data &&
+          columnName &&
+          columnValue &&
+          !(columnValue instanceof HashedString) &&
+          this.model.getTableColumnMetadata(columnName)?.hashSaltColumn
+        ) {
+          throw new BadDataException(
+            `${columnName} is a salted column and must be supplied as a HashedString, not a pre-hashed value.`,
+          );
+        }
+
         if (
           data &&
           columnName &&
@@ -559,7 +726,23 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
           columnValue instanceof HashedString
         ) {
           if (!columnValue.isValueHashed()) {
-            await columnValue.hashValue(EncryptionSecret);
+            /*
+             * The update path never runs `hash()`, so this is where an
+             * updated password gets both hashed and salted. The salt lands
+             * on `data`, which the caller turns into the SET list, so the
+             * new hash and the salt it was computed with are written by the
+             * same statement.
+             *
+             * An update matching several rows writes the same salt to all of
+             * them, which is correct: they are all being set to the same
+             * value by one statement. Per-row salts come from per-row
+             * writes.
+             */
+            await this.hashColumnValue({
+              payload: data,
+              columnName: columnName,
+              columnValue: columnValue,
+            });
           }
 
           (data as any)[columnName] = columnValue.toString();
@@ -2400,6 +2583,117 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
     await repository.manager.query(sql, params);
   }
 
+  /*
+   * Same single-statement, hook-free, no-version-bump write as
+   * `updateColumnsByIdWithoutHooks`, except it YIELDS instead of queueing:
+   * if another transaction already holds the row's lock, this write is
+   * abandoned and the method returns false. It never waits.
+   *
+   * Why this exists. A single-statement UPDATE holds its row lock for a very
+   * short time, but "short" does not mean "safe" once the arrival rate on ONE
+   * row exceeds the service rate. Postgres queues lock waiters strictly, so
+   * every waiter pins a backend for the sum of everyone ahead of it — the
+   * classic convoy. In the outage this was written for, ~25K concurrent
+   * ingest jobs across 100 worker pods funnelled onto ~2,300 Service rows and
+   * produced 1,017 active connections with 892 of them parked on row locks;
+   * the tail had been waiting 3.7 hours. Nothing about that is fixable by
+   * making the statement faster, and no Postgres tier changes it: the queue
+   * is the bug.
+   *
+   * `FOR UPDATE SKIP LOCKED` inverts it. A contended writer does zero work
+   * and returns immediately, so the number of backends blocked on any single
+   * row is capped at ONE no matter how many workers arrive together. The
+   * convoy cannot form — and cannot form even if every upstream throttle
+   * fails open at once (Redis down, fence bug, cache flush). That is the
+   * point: this is the structural backstop underneath the throttles, not a
+   * second copy of them.
+   *
+   * Use ONLY where losing the write is harmless because a concurrent writer
+   * is writing the same thing — liveness timestamps and other idempotent
+   * bookkeeping, whose contended value is by construction the value the
+   * winner is already storing. It is the WRONG primitive for a write carrying
+   * information the winner does not have (a changed attribute); for those the
+   * caller must re-attempt, and `false` is the signal to do it. Returning a
+   * boolean rather than swallowing the skip is deliberate: a silent drop here
+   * would be indistinguishable from a successful write at the call site,
+   * which is exactly how a "reliable" heartbeat quietly stops beating.
+   *
+   * Returns true when the row was updated, false when it was locked (or no
+   * longer exists).
+   */
+  @CaptureSpan()
+  public async updateColumnsByIdIfUnlockedWithoutHooks(input: {
+    id: ObjectID;
+    data: PartialEntity<TBaseModel>;
+    skipUpdateDateColumn?: boolean;
+  }): Promise<boolean> {
+    if (!input.id) {
+      throw new BadDataException("id is required");
+    }
+
+    const repository: Repository<TBaseModel> = this.getRepository();
+    const metadata: EntityMetadata = repository.metadata;
+    const driver: Driver = repository.manager.connection.driver;
+
+    const setClauses: Array<string> = [];
+    const params: Array<unknown> = [];
+
+    // Clamp on a shallow COPY — see updateColumnsByIdWithoutHooks.
+    const data: ObjectLiteral = this.truncateStringColumnsToMaxLength({
+      ...(input.data as ObjectLiteral),
+    });
+
+    for (const [propertyName, value] of Object.entries(data)) {
+      const column: ColumnMetadata | undefined =
+        metadata.findColumnWithPropertyName(propertyName);
+      if (!column) {
+        throw new BadDataException(
+          `updateColumnsByIdIfUnlockedWithoutHooks: unknown column "${propertyName}" on "${metadata.tableName}"`,
+        );
+      }
+      if (typeof value === "function") {
+        throw new BadDataException(
+          `updateColumnsByIdIfUnlockedWithoutHooks: SQL-expression values are not supported (column "${propertyName}"); pass a literal value.`,
+        );
+      }
+      params.push(driver.preparePersistentValue(value, column));
+      setClauses.push(`"${column.databaseName}" = $${params.length}`);
+    }
+
+    if (setClauses.length === 0) {
+      return false;
+    }
+
+    if (metadata.updateDateColumn && !input.skipUpdateDateColumn) {
+      setClauses.push(
+        `"${metadata.updateDateColumn.databaseName}" = CURRENT_TIMESTAMP`,
+      );
+    }
+
+    const primaryColumnName: string =
+      metadata.primaryColumns[0]?.databaseName || "_id";
+    params.push(input.id.toString());
+
+    /*
+     * The lock is taken by the sub-SELECT and inherited by the UPDATE within
+     * the same implicit transaction, so the outer write never blocks either.
+     * RETURNING is how the affected-row count comes back: TypeORM's `query()`
+     * surfaces the driver's rows and a bare UPDATE returns none, so without it
+     * a skipped write is indistinguishable from an applied one.
+     */
+    const sql: string = `UPDATE "${metadata.tableName}" SET ${setClauses.join(
+      ", ",
+    )} WHERE "${primaryColumnName}" IN (SELECT "${primaryColumnName}" FROM "${
+      metadata.tableName
+    }" WHERE "${primaryColumnName}" = $${
+      params.length
+    } FOR UPDATE SKIP LOCKED) RETURNING "${primaryColumnName}"`;
+
+    const result: unknown = await repository.manager.query(sql, params);
+
+    return Array.isArray(result) && result.length > 0;
+  }
+
   /*
    * Atomically add to numeric columns and set literal columns for one row,
    * in a SINGLE auto-committed UPDATE, with no hooks and no `version` bump.

package/Server/Services/DockerHostService.ts

@@ -5,6 +5,7 @@ import Model from "../../Models/DatabaseModels/DockerHost";
 import Label from "../../Models/DatabaseModels/Label";
 import { OnCreate } from "../Types/Database/Hooks";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import ResourceHeartbeat from "../Utils/Telemetry/ResourceHeartbeat";
 import ObjectID from "../../Types/ObjectID";
 import QueryHelper from "../Types/Database/QueryHelper";
 import OneUptimeDate from "../../Types/Date";
@@ -180,7 +181,6 @@ export class Service extends DatabaseService<Model> {
       agentVersion?: string | undefined;
     },
   ): Promise<void> {
-    const cacheKey: string = hostId.toString();
     const extrasFingerprint: string = crypto
       .createHash("sha1")
       .update(
@@ -192,34 +192,6 @@ export class Service extends DatabaseService<Model> {
       )
       .digest("hex");
 
-    let cached: string | null = null;
-    try {
-      cached = await GlobalCache.getString(LAST_SEEN_CACHE_NAMESPACE, cacheKey);
-    } catch {
-      /*
-       * Cache unavailable — fail open and refresh lastSeenAt anyway. A
-       * cache error must never skip the DB write below, otherwise the
-       * resource is wrongly marked "disconnected" while telemetry is
-       * still flowing. Mirrors shouldRunMaintenance's fail-open stance.
-       */
-      cached = null;
-    }
-
-    if (cached === extrasFingerprint) {
-      return; // same data was written recently
-    }
-
-    try {
-      await GlobalCache.setString(
-        LAST_SEEN_CACHE_NAMESPACE,
-        cacheKey,
-        extrasFingerprint,
-        { expiresInSeconds: LAST_SEEN_THROTTLE_SECONDS },
-      );
-    } catch {
-      // Best-effort throttle write; proceed with the DB update regardless.
-    }
-
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const liveness: any = {
       lastSeenAt: OneUptimeDate.getCurrentDate(),
@@ -227,66 +199,34 @@ export class Service extends DatabaseService<Model> {
     };
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const data: any = { ...liveness };
+    const metadata: any = {};
 
     if (extra?.osType) {
-      data.osType = extra.osType;
+      metadata.osType = extra.osType;
     }
     if (extra?.osVersion) {
-      data.osVersion = extra.osVersion;
+      metadata.osVersion = extra.osVersion;
     }
     if (extra?.agentVersion) {
-      data.agentVersion = extra.agentVersion;
+      metadata.agentVersion = extra.agentVersion;
     }
 
     /*
-     * Heartbeat write: a single-statement UPDATE with no hooks and no
-     * `version` bump, avoiding the hot-row Postgres lock convoy that the
-     * full updateOneById pipeline causes. See ServiceService.updateLastSeen.
-     *
-     * Collector-supplied strings are clamped to their declared column
-     * widths inside updateColumnsByIdWithoutHooks — see
-     * DatabaseService.truncateStringColumnsToMaxLength.
+     * One gated, non-blocking heartbeat write. The gates, the fail-open /
+     * fail-closed split and the liveness-only fallback all live in
+     * ResourceHeartbeat — see there for why this row's throttle used to
+     * provide no throttling at all.
      */
-    try {
-      await this.updateColumnsByIdWithoutHooks({
-        id: hostId,
-        data: data,
-      });
-    } catch (err) {
-      /*
-       * Liveness must survive bad metadata. The enriched write carries
-       * `lastSeenAt` and `otelCollectorStatus` alongside optional,
-       * collector-supplied columns; if any one of them makes Postgres
-       * reject the statement, lastSeenAt silently stops advancing and
-       * markDisconnectedHosts flips a perfectly healthy Docker host to
-       * "disconnected" 15 minutes later — with telemetry still arriving the
-       * whole time. That was issue #3006 on the Host path (a host.ip list
-       * longer than the then-varchar(500) column). Retry with liveness only
-       * so the enrichment is what gets dropped, never the heartbeat.
-       */
-      logger.warn(
-        `DockerHostService.updateLastSeen: metadata write failed for Docker host ${hostId.toString()}, falling back to a liveness-only update: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-
-      /*
-       * The throttle fingerprint was already stored, so without this the
-       * next batch would short-circuit on a cache hit and skip the retry
-       * for the rest of the window.
-       */
-      try {
-        await GlobalCache.deleteKey(LAST_SEEN_CACHE_NAMESPACE, cacheKey);
-      } catch {
-        // Best-effort; the fallback write below is what actually matters.
-      }
-
-      await this.updateColumnsByIdWithoutHooks({
-        id: hostId,
-        data: liveness,
-      });
-    }
+    await ResourceHeartbeat.write({
+      service: this,
+      id: hostId,
+      cacheNamespace: LAST_SEEN_CACHE_NAMESPACE,
+      throttleInSeconds: LAST_SEEN_THROTTLE_SECONDS,
+      liveness: liveness,
+      metadata: metadata,
+      fingerprint: extrasFingerprint,
+      describe: `docker host ${hostId.toString()}`,
+    });
   }
 
   /**

package/Server/Services/DockerSwarmClusterService.ts

@@ -5,6 +5,7 @@ import Model from "../../Models/DatabaseModels/DockerSwarmCluster";
 import Label from "../../Models/DatabaseModels/Label";
 import { OnCreate } from "../Types/Database/Hooks";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import ResourceHeartbeat from "../Utils/Telemetry/ResourceHeartbeat";
 import ObjectID from "../../Types/ObjectID";
 import QueryHelper from "../Types/Database/QueryHelper";
 import OneUptimeDate from "../../Types/Date";
@@ -182,7 +183,6 @@ export class Service extends DatabaseService<Model> {
       networkCount?: number | undefined;
     },
   ): Promise<void> {
-    const cacheKey: string = clusterId.toString();
     const extrasFingerprint: string = crypto
       .createHash("sha1")
       .update(
@@ -202,34 +202,6 @@ export class Service extends DatabaseService<Model> {
       )
       .digest("hex");
 
-    let cached: string | null = null;
-    try {
-      cached = await GlobalCache.getString(LAST_SEEN_CACHE_NAMESPACE, cacheKey);
-    } catch {
-      /*
-       * Cache unavailable — fail open and refresh lastSeenAt anyway. A
-       * cache error must never skip the DB write below, otherwise the
-       * resource is wrongly marked "disconnected" while telemetry is
-       * still flowing. Mirrors shouldRunMaintenance's fail-open stance.
-       */
-      cached = null;
-    }
-
-    if (cached === extrasFingerprint) {
-      return; // same data was written recently
-    }
-
-    try {
-      await GlobalCache.setString(
-        LAST_SEEN_CACHE_NAMESPACE,
-        cacheKey,
-        extrasFingerprint,
-        { expiresInSeconds: LAST_SEEN_THROTTLE_SECONDS },
-      );
-    } catch {
-      // Best-effort throttle write; proceed with the DB update regardless.
-    }
-
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const liveness: any = {
       lastSeenAt: OneUptimeDate.getCurrentDate(),
@@ -237,92 +209,59 @@ export class Service extends DatabaseService<Model> {
     };
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const data: any = { ...liveness };
+    const metadata: any = {};
 
     if (extra?.dockerVersion) {
-      data.dockerVersion = extra.dockerVersion;
+      metadata.dockerVersion = extra.dockerVersion;
     }
     if (extra?.swarmId) {
-      data.swarmId = extra.swarmId;
+      metadata.swarmId = extra.swarmId;
     }
     if (extra?.agentVersion) {
-      data.agentVersion = extra.agentVersion;
+      metadata.agentVersion = extra.agentVersion;
     }
     // Counts: 0 is a legitimate value — gate on undefined, not falsiness.
     if (extra?.nodeCount !== undefined) {
-      data.nodeCount = extra.nodeCount;
+      metadata.nodeCount = extra.nodeCount;
     }
     if (extra?.readyNodeCount !== undefined) {
-      data.readyNodeCount = extra.readyNodeCount;
+      metadata.readyNodeCount = extra.readyNodeCount;
     }
     if (extra?.managerNodeCount !== undefined) {
-      data.managerNodeCount = extra.managerNodeCount;
+      metadata.managerNodeCount = extra.managerNodeCount;
     }
     if (extra?.serviceCount !== undefined) {
-      data.serviceCount = extra.serviceCount;
+      metadata.serviceCount = extra.serviceCount;
     }
     if (extra?.taskCount !== undefined) {
-      data.taskCount = extra.taskCount;
+      metadata.taskCount = extra.taskCount;
     }
     if (extra?.runningTaskCount !== undefined) {
-      data.runningTaskCount = extra.runningTaskCount;
+      metadata.runningTaskCount = extra.runningTaskCount;
     }
     if (extra?.stackCount !== undefined) {
-      data.stackCount = extra.stackCount;
+      metadata.stackCount = extra.stackCount;
     }
     if (extra?.networkCount !== undefined) {
-      data.networkCount = extra.networkCount;
+      metadata.networkCount = extra.networkCount;
     }
 
     /*
-     * Heartbeat write: a single-statement UPDATE with no hooks and no
-     * `version` bump, avoiding the hot-row Postgres lock convoy that the
-     * full updateOneById pipeline causes. See ServiceService.updateLastSeen.
-     *
-     * Collector-supplied strings are clamped to their declared column
-     * widths inside updateColumnsByIdWithoutHooks — see
-     * DatabaseService.truncateStringColumnsToMaxLength.
+     * One gated, non-blocking heartbeat write. The gates, the fail-open /
+     * fail-closed split and the liveness-only fallback all live in
+     * ResourceHeartbeat — see there for why this row's throttle used to
+     * provide no throttling at all.
      */
-    try {
-      await this.updateColumnsByIdWithoutHooks({
-        id: clusterId,
-        data: data,
-      });
-    } catch (err) {
-      /*
-       * Liveness must survive bad metadata. The enriched write carries
-       * `lastSeenAt` and `otelCollectorStatus` alongside optional,
-       * collector-supplied columns; if any one of them makes Postgres
-       * reject the statement, lastSeenAt silently stops advancing and
-       * markDisconnectedClusters flips a perfectly healthy Docker Swarm
-       * cluster to "disconnected" 15 minutes later — with telemetry still
-       * arriving the whole time. That was issue #3006 on the Host path (a
-       * host.ip list longer than the then-varchar(500) column). Retry with
-       * liveness only so the enrichment is what gets dropped, never the
-       * heartbeat.
-       */
-      logger.warn(
-        `DockerSwarmClusterService.updateLastSeen: metadata write failed for Docker Swarm cluster ${clusterId.toString()}, falling back to a liveness-only update: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-
-      /*
-       * The throttle fingerprint was already stored, so without this the
-       * next batch would short-circuit on a cache hit and skip the retry
-       * for the rest of the window.
-       */
-      try {
-        await GlobalCache.deleteKey(LAST_SEEN_CACHE_NAMESPACE, cacheKey);
-      } catch {
-        // Best-effort; the fallback write below is what actually matters.
-      }
-
-      await this.updateColumnsByIdWithoutHooks({
-        id: clusterId,
-        data: liveness,
-      });
-    }
+    await ResourceHeartbeat.write({
+      service: this,
+      id: clusterId,
+      cacheNamespace: LAST_SEEN_CACHE_NAMESPACE,
+      throttleInSeconds: LAST_SEEN_THROTTLE_SECONDS,
+      liveness: liveness,
+      metadata: metadata,
+      fingerprint: extrasFingerprint,
+      describe: `docker swarm cluster ${clusterId.toString()}`,
+    });
   }
 
   /**