@checkstack/healthcheck-tcp-backend 0.3.10 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @checkstack/healthcheck-tcp-backend
 
+## 0.4.0
+
+### Minor Changes
+
+- 8cad340: Add a finer per-run transport timing breakdown to health checks.
+
+  Each run now records an optional structured `metadata.timings` (DNS, connect,
+  TLS, wait/time-to-first-byte, transfer, and a `processing` catch-all for
+  non-HTTP operation time). The run-detail view renders the phases it has, in
+  transport order, and falls back to the previous Connection + Processing split
+  for older runs that lack the finer data.
+
+  For HTTP the request is issued verbatim through `fetch` (original URL, headers,
+  and body), so request behavior is identical to a plain `fetch`. The timing is
+  measured around it: `fetch` resolves at the response headers, so wait
+  (time-to-first-byte) and transfer (body) are measured exactly on the request,
+  DNS is timed at the resolve step, and connect/TLS come from a short-lived,
+  best-effort raw `net`/`tls` probe to the same already-validated IP (the request
+  socket exposes no connect/handshake events on the Bun runtime). The probe is
+  timing-only and never fails the check. The probe validates the TLS certificate
+  (against the original hostname via SNI) like the real request does - it does not
+  disable certificate validation; an unverifiable cert simply yields no TLS-phase
+  timing rather than aborting. Other transports surface the connect and operation
+  times they already measure.
+
+  The SSRF guard now validates the resolved host (rejecting cloud-metadata /
+  link-local and operator-denied ranges) as a pre-flight check and no longer pins
+  the request to the resolved IP. Pinning rewrote the URL to the IP literal and
+  moved the host to the `Host` header, which breaks HTTP/2 origins (their
+  authority comes from the URL's `:authority`, not `Host`) - that is why real
+  hosts such as `google.com` started answering 404/429 instead of 200. The
+  pre-flight validation keeps blocking static metadata/link-local targets and
+  direct denied IP literals; the only thing dropped is DNS-rebind TOCTOU
+  protection (a narrow window that pinning closed at the cost of breaking
+  legitimate HTTP/2 requests).
+
+  The run-detail "slowest" badge no longer collides with the timing bar, and a
+  genuinely sub-millisecond phase reads as "<1 ms" instead of a bare "0 ms".
+
+### Patch Changes
+
+- 8cad340: Retune anomaly-detection defaults across every health-check strategy and the
+  hardware collector for a low-noise, problem-focused out-of-the-box experience.
+
+  The detection engine already learns a per-metric baseline, debounces with a
+  confirmation window, and applies practical-significance floors. This pass tunes
+  the per-metric **defaults** so a fresh install alerts only on genuine,
+  statistically-significant, problem-mapping deviations instead of flooding on
+  every metric that wiggles. 264 metrics were reviewed:
+
+  - **Default-disabled** the high-noise and un-baselineable classes that were
+    alerting for no good reason: raw identifiers and counts (status codes, error
+    and row counts, build counts, player and executor counts), config echoes and
+    near-constants (probe packet counts, CPU core count, total/swap memory),
+    payload-size and other run-to-run-volatile values, and deterministic values
+    like certificate days-remaining (governed by the check's own static-threshold
+    health logic, not statistics). These stay chartable and can be re-enabled per
+    field.
+  - **Hardened** the signals that should alert - latency/response/execution time
+    and availability/success/saturation percentages - with confirmation windows
+    and absolute + relative floors so brief spikes and sub-threshold jitter no
+    longer flap, and prefer percentage metrics over their absolute twins.
+
+  No detection-engine or schema changes; only per-metric `x-anomaly-*` defaults.
+  Users who had opted into any now-disabled metric keep their explicit override.
+
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+  - @checkstack/backend-api@0.25.0
+  - @checkstack/healthcheck-common@1.8.0
+  - @checkstack/common@0.17.0
+
+## 0.3.11
+
+### Patch Changes
+
+- Updated dependencies [2ec8f64]
+  - @checkstack/backend-api@0.24.1
+
 ## 0.3.10
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-tcp-backend",
-  "version": "0.3.10",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,15 +14,15 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.24.0",
-    "@checkstack/common": "0.16.0",
-    "@checkstack/healthcheck-common": "1.7.1"
+    "@checkstack/backend-api": "0.25.0",
+    "@checkstack/common": "0.17.0",
+    "@checkstack/healthcheck-common": "1.8.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.6.2"
+    "@checkstack/scripts": "0.6.3"
   },
   "description": "Checkstack healthcheck-tcp-backend plugin",
   "author": {

package/src/banner-collector.ts

@@ -47,8 +47,12 @@ const bannerResultSchema = healthResultSchema({
   hasBanner: healthResultBoolean({
     "x-chart-type": "boolean",
     "x-chart-label": "Has Banner",
-    "x-anomaly-enabled": true,
-    "x-anomaly-direction": "dominance",
+    // Whether a server emits a banner is protocol/configuration dependent and
+    // can legitimately flip run-to-run (timing, quiet protocols, partial
+    // reads). It does not map to a real availability problem on its own, so a
+    // dominance flip here is an alert-fatigue source. Charting stays available;
+    // alerting is off by default.
+    "x-anomaly-enabled": false,
   }),
   readTimeMs: healthResultNumber({
     "x-chart-type": "line",
@@ -73,13 +77,21 @@ const bannerAggregatedFields = {
     "x-chart-unit": "ms",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "lower-is-better",
+    // Latency aggregate: widen the band and require practical-significance
+    // floors so fast banner reads do not alert on small jitter.
+    "x-anomaly-sensitivity": 2,
+    "x-anomaly-confirmation-window": 3,
+    "x-anomaly-min-absolute-delta": 50,
+    "x-anomaly-min-relative-delta": 0.5,
   }),
   bannerRate: aggregatedRate({
     "x-chart-type": "gauge",
     "x-chart-label": "Banner Rate",
     "x-chart-unit": "%",
-    "x-anomaly-enabled": true,
-    "x-anomaly-direction": "higher-is-better",
+    // Banner presence is protocol/configuration dependent and varies legitimately
+    // run-to-run; its rate is not a real health signal and would alert on benign
+    // fluctuation. Charting stays available; alerting is off by default.
+    "x-anomaly-enabled": false,
   }),
 };
 

package/src/strategy.ts

@@ -11,6 +11,7 @@ import {
   mergeCounter,
   z,
   type ConnectedClient,
+  type TransportTimings,
   type InferAggregatedResult,
   baseStrategyConfigSchema,
 } from "@checkstack/backend-api";
@@ -107,6 +108,12 @@ const tcpAggregatedFields = {
     "x-chart-unit": "ms",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "lower-is-better",
+    // Latency aggregate: widen the band and require practical-significance
+    // floors so fast endpoints do not alert on small jitter.
+    "x-anomaly-sensitivity": 2,
+    "x-anomaly-confirmation-window": 3,
+    "x-anomaly-min-absolute-delta": 50,
+    "x-anomaly-min-relative-delta": 0.5,
   }),
   successRate: aggregatedRate({
     "x-chart-type": "gauge",
@@ -114,12 +121,19 @@ const tcpAggregatedFields = {
     "x-chart-unit": "%",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "higher-is-better",
+    // Availability is the primary, real signal. Debounce so a single
+    // transient failed bucket does not alert.
+    "x-anomaly-confirmation-window": 3,
   }),
   errorCount: aggregatedCounter({
     "x-chart-type": "counter",
     "x-chart-label": "Errors",
-    "x-anomaly-enabled": true,
-    "x-anomaly-direction": "lower-is-better",
+    // Raw per-bucket error count scales with how many runs land in a bucket,
+    // so it has no stable baseline and is fully redundant with successRate
+    // (which already captures the same failures as a rate). Charting stays
+    // available; alerting is owned by successRate to avoid duplicate, noisy
+    // alerts on the same failures.
+    "x-anomaly-enabled": false,
   }),
 };
 
@@ -278,10 +292,15 @@ export class TcpHealthCheckStrategy implements HealthCheckStrategy<
     const validatedConfig = this.config.validate(config);
     const socket = this.socketFactory();
 
+    const connectStart = performance.now();
     await socket.connect({
       host: validatedConfig.host,
       port: validatedConfig.port,
     });
+    // The only meaningful sub-phase for a raw TCP probe is the connect itself.
+    const timings: TransportTimings = {
+      connectMs: Math.max(0, Math.round(performance.now() - connectStart)),
+    };
 
     const client: TcpTransportClient = {
       async exec(request: TcpConnectRequest): Promise<TcpConnectResult> {
@@ -295,6 +314,7 @@ export class TcpHealthCheckStrategy implements HealthCheckStrategy<
 
     return {
       client,
+      timings,
       close: () => socket.close(),
     };
   }