feat: WS checker，支持可达性检测和单次请求-响应交互验证

src/server/checker/runner/ws/validate.ts

@@ -0,0 +1,215 @@
+import { isNumber, isString } from "es-toolkit";
+
+import type { ConfigValidationIssue } from "../../schema/issues";
+import type { CheckerValidationInput } from "../types";
+
+import {
+  isPlainRecord,
+  validateRawContentExpectations,
+  validateRawKeyedExpectations,
+  validateRawValueExpectation,
+} from "../../expect/validate";
+import { issue, joinPath } from "../../schema/issues";
+
+const ALLOWED_PROTOCOLS = new Set(["ws:", "wss:"]);
+
+export function validateWsConfig(input: CheckerValidationInput): ConfigValidationIssue[] {
+  const issues: ConfigValidationIssue[] = [];
+
+  for (let i = 0; i < input.targets.length; i++) {
+    const target = input.targets[i] as unknown;
+    if (!isPlainRecord(target)) continue;
+    if (target["type"] !== "ws") continue;
+    issues.push(...validateWsTarget(target, `targets[${i}]`));
+  }
+
+  return issues;
+}
+
+function getTargetName(target: Record<string, unknown>): string | undefined {
+  if (isString(target["name"])) return target["name"];
+  return isString(target["id"]) ? target["id"] : undefined;
+}
+
+function validateWsExpect(target: Record<string, unknown>, path: string, hasSend: boolean): ConfigValidationIssue[] {
+  const targetName = getTargetName(target);
+  const expect = target["expect"];
+  if (expect === undefined || expect === null || !isPlainRecord(expect)) return [];
+  const issues: ConfigValidationIssue[] = [];
+  const expectPath = joinPath(path, "expect");
+
+  if (expect["connected"] !== undefined && typeof expect["connected"] !== "boolean") {
+    issues.push(issue("invalid-type", joinPath(expectPath, "connected"), "必须为布尔值", targetName));
+  }
+
+  const connectedFalse = expect["connected"] === false;
+
+  if (expect["handshakeHeaders"] !== undefined) {
+    if (connectedFalse) {
+      issues.push(
+        issue(
+          "invalid-value",
+          joinPath(expectPath, "handshakeHeaders"),
+          "handshakeHeaders 断言需要 expect.connected 为 true",
+          targetName,
+        ),
+      );
+    } else {
+      issues.push(
+        ...validateRawKeyedExpectations(
+          expect["handshakeHeaders"],
+          joinPath(expectPath, "handshakeHeaders"),
+          targetName,
+          {
+            caseInsensitive: true,
+          },
+        ),
+      );
+    }
+  }
+
+  if (expect["message"] !== undefined) {
+    if (!hasSend) {
+      issues.push(issue("invalid-value", joinPath(expectPath, "message"), "message 断言需要配置 ws.send", targetName));
+    } else if (connectedFalse) {
+      issues.push(
+        issue(
+          "invalid-value",
+          joinPath(expectPath, "message"),
+          "message 断言需要 expect.connected 为 true",
+          targetName,
+        ),
+      );
+    } else {
+      issues.push(...validateRawContentExpectations(expect["message"], joinPath(expectPath, "message"), targetName));
+    }
+  }
+
+  if (expect["connectTimeMs"] !== undefined) {
+    if (connectedFalse) {
+      issues.push(
+        issue(
+          "invalid-value",
+          joinPath(expectPath, "connectTimeMs"),
+          "connectTimeMs 断言需要 expect.connected 为 true",
+          targetName,
+        ),
+      );
+    } else {
+      issues.push(
+        ...validateRawValueExpectation(expect["connectTimeMs"], joinPath(expectPath, "connectTimeMs"), targetName),
+      );
+    }
+  }
+
+  if (expect["durationMs"] !== undefined) {
+    issues.push(...validateRawValueExpectation(expect["durationMs"], joinPath(expectPath, "durationMs"), targetName));
+  }
+
+  const allowedKeys = new Set(["connected", "connectTimeMs", "durationMs", "handshakeHeaders", "message"]);
+  for (const key of Object.keys(expect)) {
+    if (!allowedKeys.has(key)) {
+      issues.push(issue("unknown-field", joinPath(expectPath, key), "是未知字段", targetName));
+    }
+  }
+
+  return issues;
+}
+
+function validateWsTarget(target: Record<string, unknown>, path: string): ConfigValidationIssue[] {
+  const issues: ConfigValidationIssue[] = [];
+  const targetName = getTargetName(target);
+  const ws = target["ws"];
+
+  if (!isPlainRecord(ws)) {
+    issues.push(issue("required", joinPath(path, "ws"), "缺少 ws.url 字段", targetName));
+    issues.push(...validateWsExpect(target, path, false));
+    return issues;
+  }
+
+  if (!isString(ws["url"]) || ws["url"].trim() === "") {
+    issues.push(issue("required", joinPath(joinPath(path, "ws"), "url"), "缺少 ws.url 字段", targetName));
+  } else {
+    try {
+      const url = new URL(ws["url"]);
+      if (!ALLOWED_PROTOCOLS.has(url.protocol)) {
+        issues.push(
+          issue(
+            "invalid-url",
+            joinPath(joinPath(path, "ws"), "url"),
+            "格式不合法，必须以 ws:// 或 wss:// 开头",
+            targetName,
+          ),
+        );
+      }
+    } catch {
+      issues.push(issue("invalid-url", joinPath(joinPath(path, "ws"), "url"), "格式不合法", targetName));
+    }
+  }
+
+  if (ws["subprotocols"] !== undefined) {
+    if (!Array.isArray(ws["subprotocols"])) {
+      issues.push(
+        issue("invalid-type", joinPath(joinPath(path, "ws"), "subprotocols"), "必须为字符串数组", targetName),
+      );
+    } else {
+      for (let i = 0; i < ws["subprotocols"].length; i++) {
+        const sp = ws["subprotocols"][i] as unknown;
+        if (!isString(sp) || sp.trim() === "") {
+          issues.push(
+            issue(
+              "invalid-value",
+              `${joinPath(joinPath(path, "ws"), "subprotocols")}[${i}]`,
+              "必须为非空字符串",
+              targetName,
+            ),
+          );
+        }
+      }
+    }
+  }
+
+  if (ws["ignoreSSL"] !== undefined && typeof ws["ignoreSSL"] !== "boolean") {
+    issues.push(issue("invalid-type", joinPath(joinPath(path, "ws"), "ignoreSSL"), "必须为布尔值", targetName));
+  }
+
+  if (
+    ws["receiveTimeout"] !== undefined &&
+    !(isNumber(ws["receiveTimeout"]) && Number.isFinite(ws["receiveTimeout"]) && ws["receiveTimeout"] >= 0)
+  ) {
+    issues.push(
+      issue("invalid-type", joinPath(joinPath(path, "ws"), "receiveTimeout"), "必须为非负有限数字", targetName),
+    );
+  }
+
+  if (ws["maxMessageBytes"] !== undefined) {
+    if (
+      !isString(ws["maxMessageBytes"]) &&
+      !(isNumber(ws["maxMessageBytes"]) && Number.isFinite(ws["maxMessageBytes"]) && ws["maxMessageBytes"] >= 0)
+    ) {
+      issues.push(
+        issue("invalid-value", joinPath(joinPath(path, "ws"), "maxMessageBytes"), "必须为合法 size 值", targetName),
+      );
+    }
+  }
+
+  const allowedWsKeys = new Set([
+    "headers",
+    "ignoreSSL",
+    "maxMessageBytes",
+    "receiveTimeout",
+    "send",
+    "subprotocols",
+    "url",
+  ]);
+  for (const key of Object.keys(ws)) {
+    if (!allowedWsKeys.has(key)) {
+      issues.push(issue("unknown-field", joinPath(joinPath(path, "ws"), key), "是未知字段", targetName));
+    }
+  }
+
+  const hasSend = isString(ws["send"]) && ws["send"].length > 0;
+  issues.push(...validateWsExpect(target, path, hasSend));
+
+  return issues;
+}