diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index fe2bc07..848461f 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -167,7 +167,9 @@ export function handleXxx(params, store: ProbeStore, method: string, mode: Runti ### 1.7 开发新 Checker -Checker 是本项目的核心扩展单元。得益于插件式注册架构，完成一个新 checker 后，**配置校验、引擎调度、数据存储、API 层会自动适配**，无需修改这些中间层代码。 +Checker 是本项目的核心扩展单元。得益于插件式注册架构，完成一个新 checker 并注册后，**配置契约组装、引擎调度、数据存储、API 层会自动走 registry 委托链路**，无需在这些中间层添加新的 type 分支。 + +当前 checker 执行链路已经注册化，但新增 checker 仍需更新中央类型定义、默认注册入口、前端展示常量、配置示例、用户/开发文档和测试。下文清单以这些必要更新为准。 以下以新增 `tcp` 类型 checker 为例，说明完整的开发步骤。 @@ -499,7 +501,7 @@ export function registerCheckers(registry = checkerRegistry): void { } ``` -注册后，以下管线会自动适配，**无需修改**： +注册后，以下管线会通过 registry 自动委托，**无需新增 type 分支**： | 模块 | 自动行为 | | ----------------------------- | ------------------------------------------------------------------------ | @@ -509,6 +511,8 @@ export function registerCheckers(registry = checkerRegistry): void { | `engine.ts` | 按 `target.type` 从 registry 取对应 checker 执行 `execute()` | | `store.ts` | 按 `target.type` 从 registry 取对应 checker 执行 `serialize()` | +注意：自动适配指上述中间层不需要新增 `switch/case` 或类型分支；开发者仍需按后续步骤更新类型、注册、前端展示、示例、文档和测试。 + #### 1.7.7 步骤六：更新前端展示 | 文件 | 修改内容 | @@ -586,8 +590,8 @@ export function registerCheckers(registry = checkerRegistry): void { - **调度**：`ProbeEngine` 用 `es-toolkit/groupBy` 按 interval 分组，每组独立 `setInterval` 定时触发 - **并发控制**：`es-toolkit/Semaphore` 限制全局最大并发数（`maxConcurrentChecks`），`acquire()` 阻塞等待 -- **Runner 选择**：`engine.runCheck()` 按 `target.type` 分发到 `runHttpCheck` 或 `runCommandCheck` -- **超时控制**：HTTP 用 `AbortController`，Command 用 `setTimeout` + `proc.kill()` +- **Runner 选择**：`engine.runCheck()` 通过 `checkerRegistry.get(target.type)` 获取 checker，并调用 `checker.execute(target, { signal })` +- **超时控制**：`ProbeEngine` 为每次检查创建 `AbortController` 并按 `target.timeoutMs` 触发 abort；checker 必须使用 `CheckerContext.signal` 感知超时，HTTP 将 signal 传给 `fetch()`，Command 在 signal abort 时 `proc.kill()` - **结果写入**：检查结果通过 `store.insertCheckResult()` 写入 SQLite，engine 通过 `targetNameToId` 缓存 name→id 映射 - **生命周期**：`start()`/`stop()` 管理定时器，`stop()` 清理所有 `setInterval` @@ -598,7 +602,7 @@ export function registerCheckers(registry = checkerRegistry): void { **HTTP 校验流程**： ``` -runHttpCheck → 收集观测(statusCode/headers) +HttpChecker.execute → 收集观测(statusCode/headers) → status → headers → (early duration) → body(按需) → (final duration) → 首个失败即停止，返回 CheckFailure ``` @@ -608,8 +612,8 @@ HTTP checker 的 `durationMs` 覆盖完整执行（含重定向、响应体读 **Command 校验流程**： ``` -runCommandCheck → 收集观测(exitCode/stdout/stderr/durationMs) -→ checkCommandExpect → exitCode → duration → stdout → stderr +CommandChecker.execute → 收集观测(exitCode/stdout/stderr/durationMs) +→ exitCode → duration → stdout → stderr → 首个失败即停止 ``` diff --git a/src/server/checker/runner/command/runner.ts b/src/server/checker/runner/command/runner.ts index 2eb4787..f7a9ba7 100644 --- a/src/server/checker/runner/command/runner.ts +++ b/src/server/checker/runner/command/runner.ts @@ -35,7 +35,7 @@ export class CommandChecker implements Checker { try { proc = Bun.spawn([t.command.exec, ...t.command.args], { cwd: t.command.cwd, - env: { ...process.env, ...t.command.env }, + env: t.command.env, stderr: "pipe", stdin: "ignore", stdout: "pipe", diff --git a/src/server/checker/runner/http/expect.ts b/src/server/checker/runner/http/expect.ts index be7b2fd..107b0ac 100644 --- a/src/server/checker/runner/http/expect.ts +++ b/src/server/checker/runner/http/expect.ts @@ -1,9 +1,7 @@ -import type { HeaderExpect, HttpExpectConfig } from "../../types"; +import type { HeaderExpect } from "../../types"; import type { ExpectResult } from "../shared/duration"; -import { checkBodyExpect } from "../shared/body"; -import { checkDuration } from "../shared/duration"; -import { errorFailure, mismatchFailure } from "../shared/failure"; +import { mismatchFailure } from "../shared/failure"; import { applyOperator } from "../shared/operator"; export function checkHeaders( @@ -45,40 +43,6 @@ export function checkHeaders( return { failure: null, matched: true }; } -export function checkHttpExpect( - statusCode: number, - headers: Record, - body: null | string, - durationMs: number, - expect?: HttpExpectConfig, -): ExpectResult { - if (!expect) { - return checkStatus(statusCode, [200]); - } - - const statusResult = checkStatus(statusCode, expect.status ?? [200]); - if (!statusResult.matched) return statusResult; - - const headersResult = checkHeaders(headers, expect.headers); - if (!headersResult.matched) return headersResult; - - if (expect.body && expect.body.length > 0) { - if (body === null) { - return { - failure: errorFailure("body", "body", "body is null but body rules are configured"), - matched: false, - }; - } - const bodyResult = checkBodyExpect(body, expect.body); - if (!bodyResult.matched) return bodyResult; - } - - const durationResult = checkDuration(durationMs, expect.maxDurationMs); - if (!durationResult.matched) return durationResult; - - return { failure: null, matched: true }; -} - export function checkStatus(statusCode: number, allowed: Array): ExpectResult { const matched = allowed.some((pattern) => { if (typeof pattern === "number") return statusCode === pattern; diff --git a/src/server/checker/store.ts b/src/server/checker/store.ts index 13c130c..83bf317 100644 --- a/src/server/checker/store.ts +++ b/src/server/checker/store.ts @@ -277,8 +277,9 @@ export class ProbeStore { const tx = this.db.transaction(() => { for (const t of targets) { const type = t.type; - const target = buildTargetDisplay(t); - const config = buildTargetConfig(t); + const serialized = checkerRegistry.get(t.type).serialize(t); + const target = serialized.target; + const config = serialized.config; const expect = t.expect ? JSON.stringify(t.expect) : null; if (existingMap.has(t.name)) { @@ -299,14 +300,6 @@ export class ProbeStore { } } -function buildTargetConfig(t: ResolvedTarget): string { - return checkerRegistry.get(t.type).serialize(t).config; -} - -function buildTargetDisplay(t: ResolvedTarget): string { - return checkerRegistry.get(t.type).serialize(t).target; -} - function ensureDir(dir: string): void { try { fsMkdirSync(dir, { recursive: true }); diff --git a/tests/server/checker/runner/command/runner.test.ts b/tests/server/checker/runner/command/runner.test.ts index d75bf4b..46dc691 100644 --- a/tests/server/checker/runner/command/runner.test.ts +++ b/tests/server/checker/runner/command/runner.test.ts @@ -7,6 +7,10 @@ import { CommandChecker } from "../../../../../src/server/checker/runner/command const checker = new CommandChecker(); +const processEnv = Object.fromEntries( + Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined), +); + function makeCtx(timeoutMs = 5000): CheckerContext { const controller = new AbortController(); setTimeout(() => controller.abort(), timeoutMs); @@ -21,7 +25,7 @@ function makeTarget( command: { args: ["hello"], cwd: "/tmp", - env: {}, + env: processEnv, exec: "echo", maxOutputBytes: 1024 * 1024, ...command, @@ -125,6 +129,22 @@ describe("CommandChecker", () => { expect(result.matched).toBe(true); }); + test("execute 使用 resolved env", async () => { + const result = await checker.execute( + makeTarget( + { + args: ["-e", "console.log(process.env.DIAL_TEST_ENV ?? '')"], + env: { DIAL_TEST_ENV: "resolved-env" }, + exec: process.execPath, + }, + { expect: { stdout: [{ contains: "resolved-env" }] } }, + ), + makeCtx(), + ); + + expect(result.matched).toBe(true); + }); + test("serialize 返回命令摘要和 config JSON", () => { const target = makeTarget({ args: ["hello"], exec: "echo" }); const s = checker.serialize(target); diff --git a/tests/server/checker/runner/http/expect.test.ts b/tests/server/checker/runner/http/expect.test.ts index d943ff9..f4043f2 100644 --- a/tests/server/checker/runner/http/expect.test.ts +++ b/tests/server/checker/runner/http/expect.test.ts @@ -1,152 +1,66 @@ import { describe, expect, test } from "bun:test"; -import { checkHttpExpect, checkStatus } from "../../../../../src/server/checker/runner/http/expect"; +import { checkHeaders, checkStatus } from "../../../../../src/server/checker/runner/http/expect"; -function obs( - overrides: { body?: null | string; durationMs?: number; headers?: Record; statusCode?: number } = {}, -) { - return { - body: overrides.body ?? "", - durationMs: overrides.durationMs ?? 100, - headers: overrides.headers ?? {}, - statusCode: overrides.statusCode ?? 200, - }; -} - -describe("checkHttpExpect", () => { - test("无 expect 配置时默认检查 status [200] 匹配成功", () => { - const r = checkHttpExpect(obs().statusCode, obs().headers, obs().body, obs().durationMs); - expect(r.matched).toBe(true); - expect(r.failure).toBeNull(); +describe("checkHeaders", () => { + test("未配置 headers expect 时匹配成功", () => { + const result = checkHeaders({}); + expect(result.matched).toBe(true); + expect(result.failure).toBeNull(); }); - test("无 expect 配置时 status 非 200 匹配失败", () => { - const r = checkHttpExpect(500, {}, "", 100); - expect(r.matched).toBe(false); - expect(r.failure).not.toBeNull(); - expect(r.failure!.phase).toBe("status"); - expect(r.failure!.kind).toBe("mismatch"); + test("字符串格式按等值匹配", () => { + const headers = { "content-type": "application/json", "x-api": "v1" }; + + expect(checkHeaders(headers, { "content-type": "application/json" }).matched).toBe(true); + expect(checkHeaders(headers, { "content-type": "text/html" }).matched).toBe(false); }); - test("status 匹配指定状态码", () => { - const cfg = { status: [200, 301] }; - expect(checkHttpExpect(200, {}, "", 100, cfg).matched).toBe(true); - expect(checkHttpExpect(301, {}, "", 100, cfg).matched).toBe(true); - expect(checkHttpExpect(404, {}, "", 100, cfg).matched).toBe(false); + test("header 名称按小写响应头匹配", () => { + const headers = { "content-type": "application/json" }; + + expect(checkHeaders(headers, { "Content-Type": "application/json" }).matched).toBe(true); }); - test("status 不匹配返回 phase=status 的失败", () => { - const r = checkHttpExpect(503, {}, "", 100, { status: [200] }); - expect(r.matched).toBe(false); - expect(r.failure!.phase).toBe("status"); - expect(r.failure!.expected).toEqual([200]); - expect(r.failure!.actual).toBe(503); + test("操作符格式匹配", () => { + const headers = { "content-type": "application/json" }; + + expect(checkHeaders(headers, { "content-type": { contains: "json" } }).matched).toBe(true); + expect(checkHeaders(headers, { "content-type": { match: "^application/" } }).matched).toBe(true); + expect(checkHeaders(headers, { "content-type": { contains: "xml" } }).matched).toBe(false); }); - test("duration 在限制内匹配成功", () => { - const r = checkHttpExpect(200, {}, "", 50, { maxDurationMs: 100 }); - expect(r.matched).toBe(true); + test("缺失 header 默认返回失败", () => { + const result = checkHeaders({}, { "x-missing": "value" }); + + expect(result.matched).toBe(false); + expect(result.failure!.phase).toBe("headers"); + expect(result.failure!.kind).toBe("mismatch"); }); - test("duration 超过限制匹配失败", () => { - const r = checkHttpExpect(200, {}, "", 200, { maxDurationMs: 100 }); - expect(r.matched).toBe(false); - expect(r.failure!.phase).toBe("duration"); - }); + test("缺失 header 且 exists=false 时匹配成功", () => { + const result = checkHeaders({}, { "x-missing": { exists: false } }); - test("duration 恰好等于限制匹配成功", () => { - const r = checkHttpExpect(200, {}, "", 100, { maxDurationMs: 100 }); - expect(r.matched).toBe(true); - }); - - test("headers 字符串格式检查（等于）", () => { - const h = { "content-type": "application/json", "x-api": "v1" }; - expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": "application/json" } }).matched).toBe(true); - expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": "text/html" } }).matched).toBe(false); - }); - - test("headers 操作符格式检查", () => { - const h = { "content-type": "application/json" }; - expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": { contains: "json" } } }).matched).toBe(true); - expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": { match: "^application/" } } }).matched).toBe( - true, - ); - expect(checkHttpExpect(200, h, "", 100, { headers: { "content-type": { contains: "xml" } } }).matched).toBe(false); - }); - - test("headers 大小写不敏感匹配", () => { - const h = { "content-type": "application/json" }; - expect(checkHttpExpect(200, h, "", 100, { headers: { "Content-Type": "application/json" } }).matched).toBe(true); - }); - - test("headers 不存在时返回失败", () => { - const r = checkHttpExpect(200, {}, "", 100, { headers: { "x-missing": "value" } }); - expect(r.matched).toBe(false); - expect(r.failure!.phase).toBe("headers"); - }); - - test("body 规则数组按顺序检查", () => { - const body = JSON.stringify({ count: 5, status: "ok" }); - const r = checkHttpExpect(200, {}, body, 100, { - body: [{ contains: "ok" }, { json: { gte: 1, path: "$.count" } }], - }); - expect(r.matched).toBe(true); - }); - - test("body 第一条规则失败立即返回", () => { - const r = checkHttpExpect(200, {}, "hello world", 100, { - body: [{ contains: "missing" }, { contains: "hello" }], - }); - expect(r.matched).toBe(false); - expect(r.failure!.path).toBe("body[0]"); - }); - - test("body 为 null 但有 body 规则时报错", () => { - const r = checkHttpExpect(200, {}, null, 100, { body: [{ contains: "test" }] }); - expect(r.matched).toBe(false); - expect(r.failure!.kind).toBe("error"); - }); - - test("完整流水线 status->headers->body->duration 全部通过", () => { - const r = checkHttpExpect(200, { "content-type": "application/json" }, JSON.stringify({ status: "healthy" }), 50, { - body: [{ json: { equals: "healthy", path: "$.status" } }], - headers: { "content-type": { contains: "json" } }, - maxDurationMs: 100, - status: [200], - }); - expect(r.matched).toBe(true); - expect(r.failure).toBeNull(); - }); - - test("完整流水线 status 和 headers 通过但 duration 失败", () => { - const r = checkHttpExpect(200, {}, "", 500, { maxDurationMs: 100, status: [200] }); - expect(r.matched).toBe(false); - expect(r.failure!.phase).toBe("duration"); - }); - - test("完整流水线 status 通过但 headers 失败", () => { - const r = checkHttpExpect(200, { "x-api": "v1" }, "", 50, { - headers: { "x-api": "v2" }, - maxDurationMs: 100, - status: [200], - }); - expect(r.matched).toBe(false); - expect(r.failure!.phase).toBe("headers"); - }); - - test("完整流水线 status/headers 通过但 body 失败", () => { - const r = checkHttpExpect(200, { "content-type": "text/plain" }, "error occurred", 50, { - body: [{ contains: "success" }], - headers: { "content-type": "text/plain" }, - maxDurationMs: 100, - status: [200], - }); - expect(r.matched).toBe(false); - expect(r.failure!.phase).toBe("body"); + expect(result.matched).toBe(true); + expect(result.failure).toBeNull(); }); }); describe("checkStatus 范围匹配", () => { + test("无 expect 配置时默认 status [200] 可由调用方使用 checkStatus 表达", () => { + const result = checkStatus(200, [200]); + expect(result.matched).toBe(true); + expect(result.failure).toBeNull(); + }); + + test("status 不匹配返回 phase=status 的失败", () => { + const result = checkStatus(503, [200]); + expect(result.matched).toBe(false); + expect(result.failure!.phase).toBe("status"); + expect(result.failure!.expected).toEqual([200]); + expect(result.failure!.actual).toBe(503); + }); + test("2xx 范围匹配 200", () => { expect(checkStatus(200, ["2xx"]).matched).toBe(true); }); @@ -163,11 +77,11 @@ describe("checkStatus 范围匹配", () => { expect(checkStatus(503, ["5xx"]).matched).toBe(true); }); - test("混合精确值与范围模式 — 精确命中", () => { + test("混合精确值与范围模式命中精确值", () => { expect(checkStatus(301, ["2xx", 301]).matched).toBe(true); }); - test("混合精确值与范围模式 — 范围命中", () => { + test("混合精确值与范围模式命中范围", () => { expect(checkStatus(204, ["2xx", 301]).matched).toBe(true); }); @@ -180,12 +94,6 @@ describe("checkStatus 范围匹配", () => { expect(checkStatus(404, [200, 201]).matched).toBe(false); }); - test("范围匹配失败返回 phase=status 的 failure", () => { - const r = checkStatus(404, ["2xx"]); - expect(r.matched).toBe(false); - expect(r.failure!.phase).toBe("status"); - }); - test("1xx 范围匹配 101", () => { expect(checkStatus(101, ["1xx"]).matched).toBe(true); });