@percy/core 1.31.13 → 1.31.14-beta.1

package/dist/percy.js

@@ -12,11 +12,12 @@ import PercyConfig from '@percy/config';
 import logger from '@percy/logger';
 import { getProxy } from '@percy/client/utils';
 import Browser from './browser.js';
+import { acquireLock, releaseLockSync } from './lock.js';
 import Pako from 'pako';
 import { base64encode, generatePromise, yieldAll, yieldTo, redactSecrets, detectSystemProxyAndLog, checkSDKVersion, processCorsIframes } from './utils.js';
 import { createPercyServer, createStaticServer } from './api.js';
 import { gatherSnapshots, createSnapshotsQueue, validateSnapshotOptions } from './snapshot.js';
-import { discoverSnapshotResources, createDiscoveryQueue } from './discovery.js';
+import { discoverSnapshotResources, createDiscoveryQueue, RESOURCE_CACHE_KEY, CACHE_STATS_KEY, DISK_SPILL_KEY } from './discovery.js';
 import Monitoring from '@percy/monitoring';
 import { WaitForJob } from './wait-for-job.js';
 const MAX_SUGGESTION_CALLS = 10;
@@ -219,6 +220,26 @@ export class Percy {
     this.readyState = 0;
     this.cliStartTime = new Date().toISOString();
     try {
+      // Per-port lock fast-fail. Acquire BEFORE any
+      // expensive setup (monitoring, proxy detection, hostname loads)
+      // so a second `percy start` on the same port refuses cheaply.
+      // Skipped when no server is configured (lock represents a port
+      // claim).
+      if (this.server) {
+        // acquireLock returns null when port === 0 (ephemeral / test
+        // fixtures); skip the exit handler in that case since there's
+        // nothing to release.
+        this._lockHandle = acquireLock({
+          port: this.port
+        });
+        if (this._lockHandle) {
+          // Synchronous unlink as last-chance cleanup if the process
+          // exits without a normal stop().
+          this._lockExitHandler = () => releaseLockSync(this._lockHandle);
+          process.on('exit', this._lockExitHandler);
+        }
+      }
+
       // started monitoring system metrics
 
       if (this.systemMonitoringEnabled()) {
@@ -262,11 +283,31 @@ export class Percy {
       await _classPrivateFieldGet(_discovery, this).end();
       await _classPrivateFieldGet(_snapshots, this).end();
 
+      // Release the lock on failed start so a retry
+      // doesn't see this aborted attempt as "already running."
+      this._releaseLock();
+
       // mark this instance as closed unless aborting
       this.readyState = error.name !== 'AbortError' ? 3 : null;
 
-      // throw an easier-to-understand error when the port is in use
-      if (error.code === 'EADDRINUSE') {
+      // throw an easier-to-understand error when the port is in use.
+      // A held lockfile fails before server.listen,
+      // so EADDRINUSE no longer fires for the "Percy already running"
+      // case — surface LockHeldError under the same legacy message
+      // (downstream tools may grep for it) but ALSO log the actionable
+      // detail (pid + lock path) so users can recover.
+      /* istanbul ignore if: in-process Percy.start tests with the
+         self-pid stale-lock optimization will reclaim and proceed to
+         server.listen() rather than throwing LockHeldError, so this
+         branch is rare under unit-test conditions. The LockHeldError
+         shape is verified by the lock.test.js SC4 spec; this branch
+         only translates it to the legacy error string. */
+      if (error.name === 'LockHeldError') {
+        this.log.error(error.message);
+        let errMsg = `Percy is already running or the port ${this.port} is in use`;
+        await this.suggestionsForFix(errMsg);
+        throw new Error(errMsg);
+      } else if (error.code === 'EADDRINUSE') {
         let errMsg = `Percy is already running or the port ${this.port} is in use`;
         await this.suggestionsForFix(errMsg);
         throw new Error(errMsg);
@@ -277,6 +318,17 @@ export class Percy {
     }
   }
 
+  // Idempotent lock release used by both the success and failure paths
+  // in start/stop.
+  _releaseLock() {
+    if (this._lockExitHandler) {
+      process.off('exit', this._lockExitHandler);
+      this._lockExitHandler = null;
+    }
+    releaseLockSync(this._lockHandle);
+    this._lockHandle = null;
+  }
+
   // Resolves once snapshot and upload queues are idle
   async *idle() {
     yield* _classPrivateFieldGet(_discovery, this).idle();
@@ -368,10 +420,76 @@ export class Percy {
       this.monitoring.stopMonitoring();
       clearTimeout(this.resetMonitoringId);
 
+      // Release per-port lock after the server
+      // socket is closed (the unlink itself is sync, but ordering
+      // after `server?.close()` keeps the post-condition that "lock
+      // present ⇒ server bound" until the very end).
+      this._releaseLock();
+
       // This issue doesn't comes under regular error logs,
       // it's detected if we just and stop percy server
       await this.checkForNoSnapshotCommandError();
+      // sendBuildLogs goes first — it's the primary egress. cache_summary is
+      // analytics, ordered after so a slow pager hop cannot delay the logs.
       await this.sendBuildLogs();
+      await this.sendCacheSummary();
+    }
+  }
+
+  // Single egress point for cache-tier telemetry. Used by sendCacheSummary
+  // (awaited at stop) and discovery's fire-and-forget eviction event. Returns
+  // early if no build is associated, swallows pager rejections — telemetry
+  // loss must never fail a build.
+  async sendCacheTelemetry(message, extra) {
+    var _this$build2;
+    if (!((_this$build2 = this.build) !== null && _this$build2 !== void 0 && _this$build2.id)) return;
+    try {
+      await this.client.sendBuildEvents(this.build.id, {
+        message,
+        cliVersion: this.client.cliVersion,
+        clientInfo: this.clientInfo,
+        extra
+      });
+    } catch (err) {
+      this.log.debug(`${message} telemetry failed`, err);
+    }
+  }
+
+  // Cache-usage summary fired at stop. The whole method is wrapped — the
+  // contract is "telemetry must never fail percy.stop()", which covers the
+  // payload-construction block as well as the egress.
+  async sendCacheSummary() {
+    try {
+      var _stats$finalDiskStats;
+      const cache = this[RESOURCE_CACHE_KEY];
+      const stats = this[CACHE_STATS_KEY];
+      if (!cache || !stats) return;
+      const cacheStats = typeof cache.stats === 'object' ? cache.stats : null;
+      // diskStore is destroyed by discovery 'end' before this runs, so fall
+      // back to the snapshot captured in stats.finalDiskStats.
+      const diskStore = this[DISK_SPILL_KEY];
+      const diskSnap = (diskStore === null || diskStore === void 0 ? void 0 : diskStore.stats) ?? stats.finalDiskStats;
+      const diskReady = diskStore ? diskStore.ready : !!((_stats$finalDiskStats = stats.finalDiskStats) !== null && _stats$finalDiskStats !== void 0 && _stats$finalDiskStats.ready);
+      await this.sendCacheTelemetry('cache_summary', {
+        cache_budget_ram_mb: stats.effectiveMaxCacheRamMB,
+        hits: (cacheStats === null || cacheStats === void 0 ? void 0 : cacheStats.hits) ?? 0,
+        misses: (cacheStats === null || cacheStats === void 0 ? void 0 : cacheStats.misses) ?? 0,
+        evictions: (cacheStats === null || cacheStats === void 0 ? void 0 : cacheStats.evictions) ?? 0,
+        peak_bytes: (cacheStats === null || cacheStats === void 0 ? void 0 : cacheStats.peakBytes) ?? stats.unsetModeBytes,
+        final_bytes: cache.calculatedSize ?? stats.unsetModeBytes,
+        entry_count: cache.size ?? 0,
+        oversize_skipped: stats.oversizeSkipped,
+        disk_spill_enabled: diskReady,
+        disk_spilled_count: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.spilled) ?? 0,
+        disk_restored_count: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.restored) ?? 0,
+        disk_spill_failures: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.spillFailures) ?? 0,
+        disk_read_failures: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.readFailures) ?? 0,
+        disk_peak_bytes: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.peakBytes) ?? 0,
+        disk_final_bytes: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.currentBytes) ?? 0,
+        disk_final_entries: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.entries) ?? 0
+      });
+    } catch (err) {
+      this.log.debug('cache_summary build failed', err);
     }
   }
   checkAndUpdateConcurrency() {
@@ -429,10 +547,10 @@ export class Percy {
   // snapshots. Once asset discovery has completed for the provided snapshots, the queued task will
   // resolve and an upload task will be queued separately.
   snapshot(options, snapshotPromise = {}) {
-    var _this$build2;
+    var _this$build3;
     if (this.readyState !== 1) {
       throw new Error('Not running');
-    } else if ((_this$build2 = this.build) !== null && _this$build2 !== void 0 && _this$build2.error) {
+    } else if ((_this$build3 = this.build) !== null && _this$build3 !== void 0 && _this$build3.error) {
       throw new Error(this.build.error);
     } else if (Array.isArray(options)) {
       return yieldAll(options.map(o => this.yield.snapshot(o, snapshotPromise)));
@@ -662,7 +780,7 @@ export class Percy {
   async sendBuildLogs() {
     if (!process.env.PERCY_TOKEN) return;
     try {
-      var _this$build3, _this$build4, _this$build5, _this$build6;
+      var _this$build4, _this$build5, _this$build6, _this$build7;
       const logsObject = {
         clilogs: logger.query(log => !['ci'].includes(log.debug))
       };
@@ -674,10 +792,10 @@ export class Percy {
         logsObject.cilogs = redactedContent;
       }
       const content = base64encode(Pako.gzip(JSON.stringify(logsObject)));
-      const referenceId = (_this$build3 = this.build) !== null && _this$build3 !== void 0 && _this$build3.id ? `build_${(_this$build4 = this.build) === null || _this$build4 === void 0 ? void 0 : _this$build4.id}` : (_this$build5 = this.build) === null || _this$build5 === void 0 ? void 0 : _this$build5.id;
+      const referenceId = (_this$build4 = this.build) !== null && _this$build4 !== void 0 && _this$build4.id ? `build_${(_this$build5 = this.build) === null || _this$build5 === void 0 ? void 0 : _this$build5.id}` : (_this$build6 = this.build) === null || _this$build6 === void 0 ? void 0 : _this$build6.id;
       const eventObject = {
         content: content,
-        build_id: (_this$build6 = this.build) === null || _this$build6 === void 0 ? void 0 : _this$build6.id,
+        build_id: (_this$build7 = this.build) === null || _this$build7 === void 0 ? void 0 : _this$build7.id,
         reference_id: referenceId,
         service_name: 'cli',
         base64encoded: true
@@ -750,9 +868,9 @@ export class Percy {
     const newAllowedDomains = Array.from(processedHosts).filter(domain => !autoConfiguredHosts.has(domain));
     const hasNewDomains = newAllowedDomains.length > 0 || newErrorHosts.size > 0;
     try {
-      var _this$build7;
+      var _this$build8;
       await this.client.updateProjectDomainConfig({
-        buildId: (_this$build7 = this.build) === null || _this$build7 === void 0 ? void 0 : _this$build7.id,
+        buildId: (_this$build8 = this.build) === null || _this$build8 === void 0 ? void 0 : _this$build8.id,
         allowedDomains: Array.from(processedHosts),
         errorDomains: Array.from(newErrorHosts)
       });

package/dist/server.js

@@ -177,11 +177,74 @@ export class Server extends http.Server {
   }
 
   // return a promise that resolves when the server closes
-  close() {
-    return new Promise(resolve => {
+  //
+  // Graceful drain. By default, stop accepting new
+  // connections, reap idle keep-alives, and let in-flight requests
+  // finish for up to `drainMs` (5s) before forcibly destroying any
+  // remaining sockets. Pass `{ drainMs: 0 }` for the legacy abrupt
+  // behavior. Uses Node 18.2+ `closeIdleConnections` /
+  // `closeAllConnections` when available, falling back to manual
+  // socket-set iteration on Node 14 (Windows CI is pinned there per
+  // .github/workflows/windows.yml).
+  async close({
+    drainMs = 5_000
+  } = {}) {
+    this.draining = true;
+    let closed = new Promise(resolve => super.close(resolve));
+
+    // Reap idle keep-alives now so they don't hold the close() callback.
+    /* istanbul ignore next: which branch fires depends on the runner's
+       Node version (CI matrix includes Node 14, where
+       closeIdleConnections is missing). The graceful behavior is
+       verified end-to-end by every existing percy.stop()-based test;
+       this if/else simply selects between the Node 18.2+ API and the
+       no-op Node 14 fallback. */
+    if (typeof this.closeIdleConnections === 'function') {
+      this.closeIdleConnections();
+    } else {
+      // Node 14 fallback: best-effort destroy of sockets without an
+      // active response. http.Server doesn't expose idleness here, so
+      // we conservatively destroy nothing in this branch and rely on
+      // the drain timeout below.
+    }
+
+    /* istanbul ignore if: legacy abrupt-close path; not used by any
+       in-tree caller post-Phase-3, kept for backwards compat with
+       SDK consumers that may pass `{ drainMs: 0 }`. */
+    if (drainMs <= 0) {
       _classPrivateFieldGet(_sockets, this).forEach(socket => socket.destroy());
-      super.close(resolve);
+      await closed;
+      return;
+    }
+
+    // Capture the force-close timer so we can clear it after the
+    // race — otherwise it fires `drainMs` later (calling
+    // closeAllConnections / socket.destroy on an already-closed
+    // server) which is a no-op in normal cases but can throw on
+    // edge-case socket states.
+    let forcedTimer;
+    /* istanbul ignore next: 5s force-close timeout fires only when
+       in-flight requests genuinely stall — exercising it under nyc
+       requires a deliberately wedged socket which interacts badly
+       with the Jasmine runner. The graceful path (where `closed`
+       wins the race) is exercised by every existing percy.stop()
+       test, and `clearTimeout(forcedTimer)` after the race ensures
+       the inner callback never runs in normal teardown. */
+    let forced = new Promise(resolve => {
+      forcedTimer = setTimeout(() => {
+        if (typeof this.closeAllConnections === 'function') {
+          this.closeAllConnections();
+        } else {
+          _classPrivateFieldGet(_sockets, this).forEach(socket => socket.destroy());
+        }
+        resolve();
+      }, drainMs).unref();
     });
+    await Promise.race([closed, forced]);
+    clearTimeout(forcedTimer);
+    // Ensure the 'close' event has fully fired even if `forced` won
+    // the race (we still need super.close()'s callback to resolve).
+    await closed;
   }
   // set request routing and handling for pathnames and methods
   route(method, pathname, handle) {

package/dist/utils.js

@@ -183,7 +183,9 @@ export async function executeDomainValidation(network, hostname, url, domainVali
     // Worker returns 'accessible' field, not 'allowed'
     if (result !== null && result !== void 0 && result.error) {
       newErrorHosts.add(hostname);
-      network.log.debug(`Domain validation: ${hostname} validated as BLOCKED - ${result === null || result === void 0 ? void 0 : result.reason}`, network.meta);
+      // Redact upstream-derived `result.reason` — may contain credentials
+      // from response bodies the validation worker echoed.
+      network.log.debug(redactSecrets(`Domain validation: ${hostname} validated as BLOCKED - ${result === null || result === void 0 ? void 0 : result.reason}`), network.meta);
       processedDomains.set(hostname, false);
       return false;
     } else if (!(result !== null && result !== void 0 && result.accessible)) {
@@ -194,8 +196,10 @@ export async function executeDomainValidation(network, hostname, url, domainVali
     }
     return false;
   } catch (error) {
-    // On error, default to allowing (fail-open for better UX)
-    network.log.warn(`Domain validation: Failed to validate ${hostname} - ${error.message}`, network.meta);
+    // On error, default to allowing (fail-open for better UX).
+    // Redact `error.message` — upstream HTTP errors can include
+    // Authorization headers / URL credentials in the failed-request text.
+    network.log.warn(redactSecrets(`Domain validation: Failed to validate ${hostname} - ${error.message}`), network.meta);
     processedDomains.set(hostname, false);
     return false;
   } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/core",
-  "version": "1.31.13",
+  "version": "1.31.14-beta.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -9,7 +9,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "latest"
+    "tag": "beta"
   },
   "engines": {
     "node": ">=14"
@@ -43,12 +43,12 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/client": "1.31.13",
-    "@percy/config": "1.31.13",
-    "@percy/dom": "1.31.13",
-    "@percy/logger": "1.31.13",
-    "@percy/monitoring": "1.31.13",
-    "@percy/webdriver-utils": "1.31.13",
+    "@percy/client": "1.31.14-beta.1",
+    "@percy/config": "1.31.14-beta.1",
+    "@percy/dom": "1.31.14-beta.1",
+    "@percy/logger": "1.31.14-beta.1",
+    "@percy/monitoring": "1.31.14-beta.1",
+    "@percy/webdriver-utils": "1.31.14-beta.1",
     "content-disposition": "^0.5.4",
     "cross-spawn": "^7.0.3",
     "extract-zip": "^2.0.1",
@@ -62,7 +62,7 @@
     "yaml": "^2.4.1"
   },
   "optionalDependencies": {
-    "@percy/cli-doctor": "1.31.13"
+    "@percy/cli-doctor": "1.31.14-beta.1"
   },
-  "gitHead": "7d28705b323836680b22f96e961ed5f39f09a56b"
+  "gitHead": "dd6957822cc94d460fd9c043a44cc4c9c5fcba23"
 }

package/test/helpers/index.js

@@ -12,6 +12,16 @@ export function mockfs(initial) {
       path.resolve(url.fileURLToPath(import.meta.url), '/../../../dom/dist/bundle.js'),
       path.resolve(url.fileURLToPath(import.meta.url), '../secretPatterns.yml'),
       p => p.includes?.('.local-chromium'),
+      // Per-port lockfiles live under ~/.percy/. They
+      // are infrastructure (not test fixture data), so route the entire
+      // directory (mkdir, writeFile, readFile, unlink) through the real
+      // fs. Matching only `/.percy/agent-` lets `writeFileSync` pass but
+      // routes `mkdirSync` for the parent through memfs, leaving the
+      // parent directory non-existent on the real fs and producing
+      // ENOENT cascades on CI. Match both POSIX `/` and Windows `\`
+      // separators because the Windows runner normalizes paths
+      // inconsistently across mkdir/writeFile/unlink.
+      p => typeof p === 'string' && /[/\\]\.percy(?:[/\\]|$)/.test(p),
       ...(initial?.$bypass ?? [])
     ]
   });