dsh-ssh-hub 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +271 -2
  3. package/cordis.patch.yml +16 -0
  4. package/icon.svg +3 -0
  5. package/lib/client.js +13975 -0
  6. package/lib/index.js +6908 -0
  7. package/lib/types/activity/history.d.ts +50 -0
  8. package/lib/types/alerting/notify.d.ts +89 -0
  9. package/lib/types/alerting/prompt-summary.d.ts +28 -0
  10. package/lib/types/alerting/rules.d.ts +135 -0
  11. package/lib/types/alerting/tools.d.ts +30 -0
  12. package/lib/types/audit/audit-log.d.ts +84 -0
  13. package/lib/types/audit/recorder.d.ts +50 -0
  14. package/lib/types/client/api.d.ts +222 -0
  15. package/lib/types/client/index.d.ts +45 -0
  16. package/lib/types/client/locales.d.ts +319 -0
  17. package/lib/types/client/native-panel.d.ts +70 -0
  18. package/lib/types/client/panel/ClusterTab.d.ts +7 -0
  19. package/lib/types/client/panel/DeployTab.d.ts +10 -0
  20. package/lib/types/client/panel/FleetTab.d.ts +10 -0
  21. package/lib/types/client/panel/HostFormDialog.d.ts +12 -0
  22. package/lib/types/client/panel/HostsTab.d.ts +25 -0
  23. package/lib/types/client/panel/LogsTab.d.ts +10 -0
  24. package/lib/types/client/panel/SshPanel.d.ts +14 -0
  25. package/lib/types/client/panel/TerminalTab.d.ts +27 -0
  26. package/lib/types/client/panel/TransferTab.d.ts +7 -0
  27. package/lib/types/client/panel/TunnelEditDialog.d.ts +15 -0
  28. package/lib/types/client/panel/TunnelsTab.d.ts +27 -0
  29. package/lib/types/client/panel/controller.d.ts +253 -0
  30. package/lib/types/client/panel/helpers.d.ts +45 -0
  31. package/lib/types/client/panel/tabs.d.ts +62 -0
  32. package/lib/types/client/panel/xterm.css.d.ts +2 -0
  33. package/lib/types/client/settings-binding.d.ts +71 -0
  34. package/lib/types/deploy/orchestrator.d.ts +158 -0
  35. package/lib/types/deploy/tools.d.ts +14 -0
  36. package/lib/types/dsh-home.d.ts +16 -0
  37. package/lib/types/engine/cluster.d.ts +19 -0
  38. package/lib/types/engine/connection-pool.d.ts +183 -0
  39. package/lib/types/engine/proxy-command.d.ts +36 -0
  40. package/lib/types/engine/pty.d.ts +32 -0
  41. package/lib/types/engine/sftp.d.ts +20 -0
  42. package/lib/types/engine/terminal-sessions.d.ts +67 -0
  43. package/lib/types/engine/tunnel-discovery.d.ts +89 -0
  44. package/lib/types/engine/tunnel-remarks.d.ts +49 -0
  45. package/lib/types/engine/tunnel.d.ts +76 -0
  46. package/lib/types/engine.d.ts +103 -0
  47. package/lib/types/http.d.ts +59 -0
  48. package/lib/types/index.d.ts +128 -0
  49. package/lib/types/inspect/checks.d.ts +118 -0
  50. package/lib/types/inspect/inspection.d.ts +111 -0
  51. package/lib/types/inspect/tools.d.ts +50 -0
  52. package/lib/types/logs/search.d.ts +131 -0
  53. package/lib/types/logs/tools.d.ts +6 -0
  54. package/lib/types/loopback.d.ts +64 -0
  55. package/lib/types/monitor/loop.d.ts +133 -0
  56. package/lib/types/monitor/metrics.d.ts +151 -0
  57. package/lib/types/mount-once.d.ts +55 -0
  58. package/lib/types/protocol.d.ts +524 -0
  59. package/lib/types/routes.d.ts +82 -0
  60. package/lib/types/security/known-hosts.d.ts +153 -0
  61. package/lib/types/security/master-secret.d.ts +157 -0
  62. package/lib/types/security/redact.d.ts +44 -0
  63. package/lib/types/security/secrets.d.ts +70 -0
  64. package/lib/types/ssh-config.d.ts +42 -0
  65. package/lib/types/store.d.ts +183 -0
  66. package/lib/types/tool-surface.d.ts +72 -0
  67. package/lib/types/tools.d.ts +56 -0
  68. package/locale/en.json +6 -0
  69. package/locale/zh.json +6 -0
  70. package/package.json +126 -6
  71. package/src/activity/history.ts +117 -0
  72. package/src/alerting/notify.ts +212 -0
  73. package/src/alerting/prompt-summary.ts +71 -0
  74. package/src/alerting/rules.ts +281 -0
  75. package/src/alerting/tools.ts +263 -0
  76. package/src/audit/audit-log.ts +199 -0
  77. package/src/audit/recorder.ts +73 -0
  78. package/src/client/api.ts +782 -0
  79. package/src/client/css-modules.d.ts +5 -0
  80. package/src/client/index.ts +150 -0
  81. package/src/client/locales.ts +654 -0
  82. package/src/client/native-panel.tsx +141 -0
  83. package/src/client/panel/ClusterTab.tsx +141 -0
  84. package/src/client/panel/DeployTab.tsx +314 -0
  85. package/src/client/panel/FleetTab.tsx +494 -0
  86. package/src/client/panel/HostFormDialog.tsx +289 -0
  87. package/src/client/panel/HostsTab.tsx +395 -0
  88. package/src/client/panel/LogsTab.tsx +208 -0
  89. package/src/client/panel/SshPanel.tsx +105 -0
  90. package/src/client/panel/TerminalTab.tsx +550 -0
  91. package/src/client/panel/TransferTab.tsx +238 -0
  92. package/src/client/panel/TunnelEditDialog.tsx +174 -0
  93. package/src/client/panel/TunnelsTab.tsx +328 -0
  94. package/src/client/panel/controller.ts +507 -0
  95. package/src/client/panel/helpers.ts +84 -0
  96. package/src/client/panel/panel.module.css +1734 -0
  97. package/src/client/panel/tabs.ts +52 -0
  98. package/src/client/panel/xterm.css.ts +2 -0
  99. package/src/client/settings-binding.ts +184 -0
  100. package/src/deploy/orchestrator.ts +326 -0
  101. package/src/deploy/tools.ts +225 -0
  102. package/src/dsh-home.ts +42 -0
  103. package/src/engine/cluster.ts +60 -0
  104. package/src/engine/connection-pool.ts +721 -0
  105. package/src/engine/proxy-command.ts +248 -0
  106. package/src/engine/pty.ts +78 -0
  107. package/src/engine/sftp.ts +229 -0
  108. package/src/engine/terminal-sessions.ts +280 -0
  109. package/src/engine/tunnel-discovery.ts +353 -0
  110. package/src/engine/tunnel-remarks.ts +120 -0
  111. package/src/engine/tunnel.ts +300 -0
  112. package/src/engine.ts +195 -0
  113. package/src/http.ts +127 -0
  114. package/src/index.ts +690 -0
  115. package/src/inspect/checks.ts +251 -0
  116. package/src/inspect/inspection.ts +321 -0
  117. package/src/inspect/tools.ts +366 -0
  118. package/src/logs/search.ts +251 -0
  119. package/src/logs/tools.ts +160 -0
  120. package/src/loopback.ts +119 -0
  121. package/src/monitor/loop.ts +265 -0
  122. package/src/monitor/metrics.ts +333 -0
  123. package/src/mount-once.ts +142 -0
  124. package/src/protocol.ts +534 -0
  125. package/src/routes.ts +998 -0
  126. package/src/security/known-hosts.ts +342 -0
  127. package/src/security/master-secret.ts +334 -0
  128. package/src/security/redact.ts +119 -0
  129. package/src/security/secrets.ts +152 -0
  130. package/src/ssh-config.ts +182 -0
  131. package/src/store.ts +757 -0
  132. package/src/tool-surface.ts +96 -0
  133. package/src/tools.ts +550 -0
@@ -0,0 +1,160 @@
1
+ /**
2
+ * Agent tools for the cross-host log search.
3
+ */
4
+
5
+ import { defineTool } from '@deepseek-ai/dsh-tools'
6
+ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
7
+ import type { SshEngine } from '../engine.ts'
8
+ import { renderLogSearch, searchLogs, type LogSearchResult } from './search.ts'
9
+
10
+ /** One text content block (the only render shape these tools emit). */
11
+ function text(value: string): ContentBlock[] {
12
+ return [{ type: 'text', text: value }]
13
+ }
14
+
15
+ /** The log-search tool. */
16
+ export function hubLogSearchTool(engine: SshEngine) {
17
+ return defineTool({
18
+ name: 'hub_log_search',
19
+ description: 'Search logs across many SSH hosts at once. Reads the systemd journal or log files under a directory on each host — nothing is installed on the remote side and nothing is written. Matches are bounded per host, and the result says so when it was truncated. Use this to trace a failure across the fleet; use ssh_exec for a one-off command.',
20
+ parameters: {
21
+ pattern: { type: 'string', required: true, description: 'The text to search for (a fixed string, not a regular expression).' },
22
+ aliases: { type: 'array', items: { type: 'string' }, description: 'Host aliases to search. Optional when environment or tags is given.' },
23
+ environment: { type: 'string', description: 'Search only hosts with this environment label (exact match).' },
24
+ tags: { type: 'array', items: { type: 'string' }, description: 'Search only hosts carrying ALL of these tags.' },
25
+ source: { type: 'string', enum: ['journal', 'files'], description: 'Where to search: the systemd journal, or files under a directory (default journal).' },
26
+ directory: { type: 'string', description: 'The log directory, when the source is files (default /var/log).' },
27
+ unit: { type: 'string', description: 'Filter the journal by systemd unit, e.g. nginx.' },
28
+ sinceSeconds: { type: 'integer', description: 'Only search journal entries newer than this many seconds ago.' },
29
+ maxLinesPerHost: { type: 'integer', description: 'How many matching lines to keep per host (default 50).' },
30
+ },
31
+ output: {
32
+ schema: {
33
+ type: 'object',
34
+ additionalProperties: false,
35
+ properties: {
36
+ ok: { type: 'boolean', required: true },
37
+ targets: { type: 'array', items: { type: 'string' } },
38
+ results: {
39
+ type: 'array',
40
+ items: {
41
+ type: 'object',
42
+ additionalProperties: false,
43
+ properties: {
44
+ alias: { type: 'string', required: true },
45
+ ok: { type: 'boolean', required: true },
46
+ matches: { type: 'integer', required: true },
47
+ totalMatches: { type: 'integer' },
48
+ lines: { type: 'array', items: { type: 'string' } },
49
+ truncated: { type: 'boolean' },
50
+ error: { type: 'string' },
51
+ },
52
+ },
53
+ required: true,
54
+ },
55
+ totalLines: { type: 'integer', required: true },
56
+ truncated: { type: 'boolean', required: true },
57
+ durationMs: { type: 'integer', required: true },
58
+ error: { type: 'string' },
59
+ },
60
+ },
61
+ render: (_args, value: {
62
+ ok: boolean
63
+ targets?: string[]
64
+ results: Array<{ alias: string; ok: boolean; matches: number; totalMatches?: number; lines?: string[]; truncated?: boolean; error?: string }>
65
+ totalLines: number
66
+ truncated: boolean
67
+ durationMs: number
68
+ error?: string
69
+ }) => {
70
+ if (value.error !== undefined) return text(`日志检索失败:${value.error}`)
71
+ const summary = `跨机日志检索:${value.targets?.length ?? 0} 台主机,命中 ${value.totalLines} 行,耗时 ${value.durationMs}ms`
72
+ const lines: string[] = [summary]
73
+ if (value.truncated) lines.push('(部分主机输出被截断,命中数可能高于显示行数)')
74
+ for (const result of value.results) {
75
+ if (!result.ok) {
76
+ lines.push('', `${result.alias}:检索失败:${result.error ?? '未知错误'}`)
77
+ continue
78
+ }
79
+ if (result.matches === 0) continue
80
+ lines.push('', `── ${result.alias}(共 ${result.totalMatches ?? result.matches} 条命中)`)
81
+ for (const line of result.lines ?? []) lines.push(line)
82
+ }
83
+ return text(lines.join('\n'))
84
+ },
85
+ },
86
+ async execute(args) {
87
+ const targets = resolveLogTargets(engine, args.aliases, args.environment, args.tags)
88
+ if (targets.length === 0) {
89
+ return {
90
+ ok: true,
91
+ targets: [],
92
+ results: [],
93
+ totalLines: 0,
94
+ truncated: false,
95
+ durationMs: 0,
96
+ }
97
+ }
98
+ const result = await searchLogs(engine, {
99
+ source: args.source === 'files' ? 'files' : 'journal',
100
+ pattern: args.pattern,
101
+ ...(args.directory !== undefined ? { directory: args.directory } : {}),
102
+ ...(args.unit !== undefined ? { unit: args.unit } : {}),
103
+ ...(args.sinceSeconds !== undefined ? { since: Math.floor(Date.now() / 1000) - args.sinceSeconds } : {}),
104
+ ...(args.maxLinesPerHost !== undefined ? { maxLinesPerHost: args.maxLinesPerHost } : {}),
105
+ }, targets)
106
+ return {
107
+ ok: result.ok,
108
+ targets: result.targets,
109
+ results: result.results.map(host => ({
110
+ alias: host.alias,
111
+ ok: host.ok,
112
+ matches: host.lines.length,
113
+ ...(host.totalMatches !== undefined ? { totalMatches: host.totalMatches } : {}),
114
+ lines: host.lines,
115
+ ...(host.truncated === true ? { truncated: true } : {}),
116
+ ...(host.error !== undefined ? { error: host.error } : {}),
117
+ })),
118
+ totalLines: result.totalLines,
119
+ truncated: result.truncated,
120
+ durationMs: result.durationMs,
121
+ }
122
+ },
123
+ })
124
+ }
125
+
126
+ /**
127
+ * Resolve the hosts to search.
128
+ *
129
+ * @param engine - the SSH engine.
130
+ * @param aliases - explicit aliases.
131
+ * @param environment - an environment label.
132
+ * @param tags - tags that must all be present.
133
+ * @returns the selected aliases.
134
+ */
135
+ function resolveLogTargets(
136
+ engine: SshEngine,
137
+ aliases?: string[],
138
+ environment?: string,
139
+ tags?: string[],
140
+ ): string[] {
141
+ const hasAlias = aliases !== undefined && aliases.length > 0
142
+ const hasEnvironment = environment !== undefined && environment !== ''
143
+ const hasTags = tags !== undefined && tags.length > 0
144
+ if (!hasAlias && !hasEnvironment && !hasTags) {
145
+ throw new Error('hub_log_search requires aliases, environment, or tags to limit the target set')
146
+ }
147
+ let hosts = engine.store.list()
148
+ if (hasAlias) {
149
+ const wanted = new Set(aliases as string[])
150
+ hosts = hosts.filter(host => wanted.has(host.alias))
151
+ }
152
+ if (hasEnvironment) {
153
+ hosts = hosts.filter(host => host.environment === environment)
154
+ }
155
+ if (hasTags) {
156
+ const wanted = tags as string[]
157
+ hosts = hosts.filter(host => wanted.every(tag => host.tags.includes(tag)))
158
+ }
159
+ return hosts.map(host => host.alias)
160
+ }
@@ -0,0 +1,119 @@
1
+ // Generated by scripts/sync-shared.mjs from shared/host/loopback.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
2
+ /**
3
+ * Loopback trust fence shared by the host route families: socket address,
4
+ * Host header, and browser same-origin markers. Packages receive this file as
5
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
6
+ * re-run the sync instead of editing a copy.
7
+ *
8
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
9
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
10
+ * markers (sec-fetch-site and Origin) for the request-level fence.
11
+ *
12
+ * A reverse proxy in front of the host rewrites the Host header to its own
13
+ * upstream literal (a Cloudflare tunnel, frp and an nginx reverse proxy all
14
+ * dial 127.0.0.1:<port>), and the socket the origin sees is the proxy's, which
15
+ * is loopback by construction. Both halves of the fence then hold for a public
16
+ * request. Forwarding headers are the signal that a hop stands in between: a
17
+ * request that carries CF-Connecting-IP or X-Forwarded-For is answered through
18
+ * a proxy and is never treated as a local one (issue #1906).
19
+ *
20
+ * An operator who runs that proxy or tunnel themselves can opt into the
21
+ * narrower case: isForwardedLoopbackRequest describes a forwarded request that
22
+ * still landed on this machine's loopback upstream, and a route family admits
23
+ * it only behind its own default-off switch (issue #1918).
24
+ * @module dsh-web-shared/host/loopback
25
+ */
26
+
27
+ import type { IncomingMessage } from 'node:http'
28
+
29
+ /** IPv4 127/8 predicate (four decimal octets, first == 127). */
30
+ export function isIPv4Loopback(v4: string): boolean {
31
+ const parts = v4.split('.')
32
+ return parts.length === 4
33
+ && parts[0] === '127'
34
+ && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
35
+ }
36
+
37
+ /** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
38
+ export function isLoopbackAddress(address: string | undefined): boolean {
39
+ if (address === undefined) return false
40
+ const normalized = address.toLowerCase()
41
+ if (normalized === '::1') return true
42
+ if (normalized.startsWith('::ffff:')) return isIPv4Loopback(normalized.slice('::ffff:'.length))
43
+ return isIPv4Loopback(normalized)
44
+ }
45
+
46
+ /** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
47
+ export function isLoopbackHostname(hostname: string): boolean {
48
+ if (hostname === 'localhost' || hostname === '[::1]') return true
49
+ return isIPv4Loopback(hostname)
50
+ }
51
+
52
+ /**
53
+ * Whether a reverse proxy stood between the client and this host: the request
54
+ * carries CF-Connecting-IP or X-Forwarded-For. Either header is stamped by a
55
+ * hop that forwards traffic, so the request did not originate on this machine.
56
+ * @param request - node HTTP request.
57
+ * @returns true when a forwarding header is present.
58
+ */
59
+ export function isProxiedRequest(request: IncomingMessage): boolean {
60
+ return request.headers['cf-connecting-ip'] !== undefined
61
+ || request.headers['x-forwarded-for'] !== undefined
62
+ }
63
+
64
+ /**
65
+ * Request-level trust fence: a loopback socket address AND a loopback Host
66
+ * header, plus browser same-origin markers. The socket address is
67
+ * authoritative for a direct connection; a request that carries a forwarding
68
+ * header is refused outright, because a proxy in front of the host makes both
69
+ * the socket address and the Host header describe the proxy rather than the
70
+ * client. X-Forwarded-For is therefore never evidence *for* loopback.
71
+ */
72
+ export function isLoopbackRequest(request: IncomingMessage): boolean {
73
+ if (!isLoopbackAddress(request.socket.remoteAddress)) return false
74
+ if (isProxiedRequest(request)) return false
75
+ const host = request.headers.host
76
+ if (typeof host !== 'string') return false
77
+ let hostUrl: URL
78
+ try {
79
+ hostUrl = new URL('http://' + host)
80
+ } catch {
81
+ return false
82
+ }
83
+ if (!isLoopbackHostname(hostUrl.hostname)) return false
84
+ if (request.headers['sec-fetch-site'] === 'cross-site') return false
85
+ const origin = request.headers.origin
86
+ if (origin === undefined) return true
87
+ try {
88
+ return new URL(origin).host === hostUrl.host
89
+ } catch {
90
+ return false
91
+ }
92
+ }
93
+
94
+ /**
95
+ * Whether a forwarded request landed on this machine's loopback upstream: a
96
+ * forwarding header (the proxy's own stamp), a loopback socket address (the
97
+ * proxy dials 127.0.0.1:<port>), and a loopback Host header (the proxy rewrote
98
+ * the authority to its upstream literal).
99
+ *
100
+ * This is a fact about the route, not a trust decision. A public request to a
101
+ * tunnel satisfies all three by construction, because the proxy is the client
102
+ * of this process: only a caller that operates the proxy can decide it stands
103
+ * for the browser, which is why every consumer keeps this behind an explicit
104
+ * default-off switch and its own browser markers. isLoopbackRequest is
105
+ * unchanged and still refuses a forwarded request (issue #1906).
106
+ * @param request - node HTTP request.
107
+ * @returns true when a forwarding header, a loopback socket, and a loopback Host all hold.
108
+ */
109
+ export function isForwardedLoopbackRequest(request: IncomingMessage): boolean {
110
+ if (!isProxiedRequest(request)) return false
111
+ if (!isLoopbackAddress(request.socket.remoteAddress)) return false
112
+ const host = request.headers.host
113
+ if (typeof host !== 'string') return false
114
+ try {
115
+ return isLoopbackHostname(new URL('http://' + host).hostname)
116
+ } catch {
117
+ return false
118
+ }
119
+ }
@@ -0,0 +1,265 @@
1
+ /**
2
+ * The monitoring loop: inspection on a timer, feeding the alert engine.
3
+ *
4
+ * This is the piece that turns the inspection layer from "an agent can ask
5
+ * for a health check" into "the fleet is watched". Without it, an alert
6
+ * only advances when a human (or an agent) happens to run hub_inspect, so a
7
+ * disk filling up at 03:00 is discovered whenever someone next looks —
8
+ * which is exactly the failure a monitoring tool exists to prevent.
9
+ *
10
+ * The loop is deliberately conservative, because its failure mode is
11
+ * expensive:
12
+ *
13
+ * - **One round at a time.** A round that outlasts the interval does not
14
+ * stack: the next tick is skipped, not queued. Fifty hosts with a slow
15
+ * connection would otherwise pile up overlapping rounds until the pool
16
+ * is exhausted.
17
+ * - **The timer belongs to the plugin's fiber.** `ctx.timer.interval`
18
+ * disposes with the fiber, so disabling the plugin stops the loop
19
+ * instead of leaving an orphan timer probing servers forever.
20
+ * - **A failed round is not a fleet-wide alert.** If every host fails, the
21
+ * cause is almost always the local link or the pool, not fifty machines
22
+ * dying at once. The round is reported as a degraded round, and the
23
+ * alert engine's null-freeze keeps the previous states rather than
24
+ * inventing fifty recoveries.
25
+ */
26
+
27
+ import type { SshEngine } from '../engine.ts'
28
+ import type { Inspector, InspectionRound } from '../inspect/inspection.ts'
29
+ import { findCheck, formatValue } from '../inspect/checks.ts'
30
+ import type { AlertEngine, AlertNotification, AlertRule } from '../alerting/rules.ts'
31
+ import type { AlertEvent } from '../alerting/tools.ts'
32
+
33
+ /** Where the tick callback gets its timer from (the cordis timer service). */
34
+ export interface TimerHost {
35
+ interval(callback: () => void, delay: number): () => void
36
+ }
37
+
38
+ /** Monitoring loop options. */
39
+ export interface MonitorOptions {
40
+ /** How often to run a round, in milliseconds. */
41
+ intervalMs: number
42
+ /** The hosts to watch (a fixed set captured at start; re-resolved per round). */
43
+ targets?: () => string[]
44
+ /** Which checks to run (default: all built-in checks). */
45
+ checks?: string[]
46
+ /** Per-command timeout. */
47
+ timeoutMs?: number
48
+ /** The alert rules. */
49
+ rules: AlertRule[]
50
+ }
51
+
52
+ /** A round's outcome as the loop records it. */
53
+ export interface MonitorTick {
54
+ /** Epoch milliseconds when the round started. */
55
+ at: number
56
+ /** Whether the round actually ran (false when skipped as overlapping). */
57
+ ran: boolean
58
+ /** How many hosts were inspected. */
59
+ hosts: number
60
+ /** How many results breached their threshold. */
61
+ breaches: number
62
+ /** How many probe failures (unreadable values) occurred. */
63
+ blind: number
64
+ /** The notifications this round produced. */
65
+ notifications: AlertNotification[]
66
+ /** Why the round did not run, when it did not. */
67
+ skippedBecause?: string
68
+ }
69
+
70
+ /**
71
+ * The monitoring loop.
72
+ *
73
+ * Owns no state beyond `running` and the recent ticks: the inspection
74
+ * history and the alert state each have their own store, so a restart of
75
+ * the loop does not lose either.
76
+ */
77
+ export class Monitor {
78
+ private readonly engine: SshEngine
79
+ private readonly inspector: Inspector
80
+ private readonly alerts: AlertEngine
81
+ private readonly events: AlertEvent[]
82
+ private readonly onNotify?: (notification: AlertNotification) => void | Promise<void>
83
+ private readonly options: MonitorOptions
84
+ /** Recent ticks, newest last (bounded). */
85
+ readonly ticks: MonitorTick[] = []
86
+ /** The interval disposer, while the loop runs. */
87
+ private dispose: (() => void) | undefined
88
+ /** Whether a round is in flight (the overlap guard). */
89
+ private inFlight = false
90
+ /** The last round, for the panel to read without re-reading the file. */
91
+ lastRound: InspectionRound | undefined
92
+
93
+ constructor(
94
+ engine: SshEngine,
95
+ inspector: Inspector,
96
+ alerts: AlertEngine,
97
+ events: AlertEvent[],
98
+ options: MonitorOptions,
99
+ onNotify?: (notification: AlertNotification) => void | Promise<void>,
100
+ ) {
101
+ this.engine = engine
102
+ this.inspector = inspector
103
+ this.alerts = alerts
104
+ this.events = events
105
+ this.options = options
106
+ this.onNotify = onNotify
107
+ }
108
+
109
+ /** Whether the loop is currently armed. */
110
+ get running(): boolean {
111
+ return this.dispose !== undefined
112
+ }
113
+
114
+ /**
115
+ * Start the loop.
116
+ *
117
+ * A second start is a no-op rather than a second timer: two timers would
118
+ * double every probe against the fleet.
119
+ *
120
+ * @param timer - the cordis timer service.
121
+ * @returns the disposer that stops the loop.
122
+ */
123
+ start(timer: TimerHost): () => void {
124
+ if (this.dispose !== undefined) return this.dispose
125
+ const delay = Math.max(1000, this.options.intervalMs)
126
+ const stop = timer.interval(() => { void this.tick() }, delay)
127
+ this.dispose = () => {
128
+ stop()
129
+ this.dispose = undefined
130
+ }
131
+ return this.dispose
132
+ }
133
+
134
+ /** Stop the loop (idempotent). */
135
+ stop(): void {
136
+ this.dispose?.()
137
+ }
138
+
139
+ /**
140
+ * Run one round now.
141
+ *
142
+ * @returns the round's outcome, or undefined when a round was already in
143
+ * flight (the tick is skipped, not queued).
144
+ */
145
+ async tick(): Promise<MonitorTick | undefined> {
146
+ if (this.inFlight) {
147
+ this.record({
148
+ at: Date.now(),
149
+ ran: false,
150
+ hosts: 0,
151
+ breaches: 0,
152
+ blind: 0,
153
+ notifications: [],
154
+ skippedBecause: '上一轮尚未结束',
155
+ })
156
+ return undefined
157
+ }
158
+ this.inFlight = true
159
+ const startedAt = Date.now()
160
+ try {
161
+ const targets = this.options.targets?.() ?? []
162
+ if (targets.length === 0) {
163
+ this.record({
164
+ at: startedAt,
165
+ ran: false,
166
+ hosts: 0,
167
+ breaches: 0,
168
+ blind: 0,
169
+ notifications: [],
170
+ skippedBecause: '没有需要巡检的主机',
171
+ })
172
+ return undefined
173
+ }
174
+ const round = await this.inspector.run(this.engine, targets, this.options.checks, this.options.timeoutMs)
175
+ this.lastRound = round
176
+ const breaches = round.results.filter(result => result.breached).length
177
+ const blind = round.results.filter(result => result.value === null).length
178
+ const notifications = this.alerts.evaluate(this.options.rules, round.results, this.options.intervalMs)
179
+ for (const notification of notifications) {
180
+ this.events.push({
181
+ ruleId: notification.ruleId,
182
+ alias: notification.alias,
183
+ kind: notification.kind,
184
+ value: notification.value,
185
+ at: notification.at,
186
+ })
187
+ // A notification channel that throws must not kill the loop: the
188
+ // alert is already recorded, and losing the next round would be a
189
+ // worse outcome than a missed page.
190
+ try {
191
+ await this.onNotify?.(notification)
192
+ } catch { /* recorded above; delivery failure is reported by the sender */ }
193
+ }
194
+ // Bound the event feed: an unbounded array in a long-running process
195
+ // is a leak, and the panel only shows the recent tail anyway.
196
+ if (this.events.length > 500) this.events.splice(0, this.events.length - 500)
197
+ const tick: MonitorTick = {
198
+ at: startedAt,
199
+ ran: true,
200
+ hosts: targets.length,
201
+ breaches,
202
+ blind,
203
+ notifications,
204
+ }
205
+ this.record(tick)
206
+ return tick
207
+ } finally {
208
+ this.inFlight = false
209
+ }
210
+ }
211
+
212
+ /** Append a tick to the bounded history. */
213
+ private record(tick: MonitorTick): void {
214
+ this.ticks.push(tick)
215
+ if (this.ticks.length > 100) this.ticks.splice(0, this.ticks.length - 100)
216
+ }
217
+
218
+ /**
219
+ * The current state, for the status route and the panel.
220
+ *
221
+ * @returns the loop's health summary.
222
+ */
223
+ status(): {
224
+ running: boolean
225
+ intervalMs: number
226
+ lastTick?: MonitorTick
227
+ nextTickAt?: number
228
+ hosts: number
229
+ lastRoundAt?: number
230
+ } {
231
+ const last = this.ticks[this.ticks.length - 1]
232
+ return {
233
+ running: this.running,
234
+ intervalMs: this.options.intervalMs,
235
+ ...(last !== undefined ? { lastTick: last } : {}),
236
+ ...(last !== undefined && this.running ? { nextTickAt: last.at + this.options.intervalMs } : {}),
237
+ hosts: this.options.targets?.().length ?? 0,
238
+ ...(this.lastRound !== undefined ? { lastRoundAt: this.lastRound.startedAt } : {}),
239
+ }
240
+ }
241
+ }
242
+
243
+ /**
244
+ * Render one round as operator-facing text.
245
+ *
246
+ * Used by the status route and the panel's inspection tab, so both show the
247
+ * same thing the agent sees.
248
+ *
249
+ * @param round - the round.
250
+ * @returns the report text.
251
+ */
252
+ export function renderRound(round: InspectionRound): string {
253
+ const lines: string[] = [
254
+ `巡检 ${round.targets.length} 台主机,耗时 ${round.durationMs}ms`,
255
+ ]
256
+ const breached = round.results.filter(result => result.breached)
257
+ const blind = round.results.filter(result => result.value === null)
258
+ lines.push(`超限 ${breached.length} 项,探针失联 ${blind.length} 项`)
259
+ for (const result of breached) {
260
+ const check = findCheck(result.checkId)
261
+ const label = result.checkId
262
+ lines.push(` ${result.alias} | ${label} | ${check === undefined ? String(result.value) : formatValue(check, result.value)}`)
263
+ }
264
+ return lines.join('\n')
265
+ }