docs: document gateway server runtime

steipete · steipete · commit f24ae91842d6 · 2026-06-04T18:35:26.000-04:00
diff --git a/src/gateway/server/close-reason.ts b/src/gateway/server/close-reason.ts
@@ -1,3 +1,4 @@
+// Close reason helpers keep WebSocket handshake failure text within RFC byte limits.
 import { Buffer } from "node:buffer";
 
 /**
diff --git a/src/gateway/server/event-loop-health.test.ts b/src/gateway/server/event-loop-health.test.ts
@@ -1,3 +1,4 @@
+// Event-loop health tests cover delay, CPU, and utilization degradation classification.
 import type { monitorEventLoopDelay, performance } from "node:perf_hooks";
 import { describe, expect, it, vi } from "vitest";
 import {
diff --git a/src/gateway/server/event-loop-health.ts b/src/gateway/server/event-loop-health.ts
@@ -1,3 +1,4 @@
+// Event-loop health monitor samples delay, utilization, and CPU pressure for gateway readiness snapshots.
 import { monitorEventLoopDelay, performance } from "node:perf_hooks";
 
 const EVENT_LOOP_MONITOR_RESOLUTION_MS = 20;
diff --git a/src/gateway/server/health-state.test.ts b/src/gateway/server/health-state.test.ts
@@ -1,3 +1,4 @@
+// Health-state tests cover probe coalescing, sensitive snapshots, and broadcast version behavior.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { HealthSummary } from "../../commands/health.js";
 
diff --git a/src/gateway/server/health-state.ts b/src/gateway/server/health-state.ts
@@ -1,3 +1,4 @@
+// Gateway health state builds snapshots, caches health probes, and broadcasts health/presence version changes.
 import type { Snapshot } from "../../../packages/gateway-protocol/src/index.js";
 import { resolveDefaultAgentId } from "../../agents/agent-scope.js";
 import { getHealthSnapshot, type HealthSummary } from "../../commands/health.js";
diff --git a/src/gateway/server/hook-client-ip-config.ts b/src/gateway/server/hook-client-ip-config.ts
@@ -1,3 +1,4 @@
+// Hook client-IP config adapts gateway trusted-proxy settings for hook request handling.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { HookClientIpConfig } from "./hooks-request-handler.js";
 
diff --git a/src/gateway/server/hooks-request-handler.ts b/src/gateway/server/hooks-request-handler.ts
@@ -1,3 +1,4 @@
+// Hook request handler validates hook tokens, applies mappings, dedupes requests, and dispatches wake or agent work.
 import { createHash } from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { createSubsystemLogger } from "../../logging/subsystem.js";
diff --git a/src/gateway/server/hooks.ts b/src/gateway/server/hooks.ts
@@ -1,3 +1,4 @@
+// Gateway hook server wiring translates external hook requests into wake events or isolated agent runs.
 import { randomUUID } from "node:crypto";
 import {
   resolveDateTimestampMs,
diff --git a/src/gateway/server/http-listen.test.ts b/src/gateway/server/http-listen.test.ts
@@ -1,3 +1,4 @@
+// Gateway HTTP listener tests cover retry behavior for lock contention and listen failures.
 import { EventEmitter } from "node:events";
 import type { Server as HttpServer } from "node:http";
 import { describe, expect, it, vi } from "vitest";
diff --git a/src/gateway/server/plugin-node-capability-auth.ts b/src/gateway/server/plugin-node-capability-auth.ts
@@ -1,3 +1,4 @@
+// Plugin node capability auth lets node-issued route capabilities supplement normal bearer gateway auth.
 import type { IncomingMessage } from "node:http";
 import type { AuthRateLimiter } from "../auth-rate-limit.js";
 import {
diff --git a/src/gateway/server/plugin-route-runtime-scopes.ts b/src/gateway/server/plugin-route-runtime-scopes.ts
@@ -1,3 +1,4 @@
+// Plugin route runtime scopes map authenticated HTTP callers to operator scopes exposed inside plugin handlers.
 import type { IncomingMessage } from "node:http";
 import {
   getHeader,
diff --git a/src/gateway/server/plugins-http.test.ts b/src/gateway/server/plugins-http.test.ts
@@ -1,3 +1,4 @@
+// Plugin HTTP routing tests cover route matching, gateway auth decisions, and upgrade dispatch.
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/gateway/server/plugins-http.ts b/src/gateway/server/plugins-http.ts
@@ -1,3 +1,4 @@
+// Plugin HTTP routing dispatches registered plugin routes, upgrades, auth policy, and runtime request scope.
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
 import {
diff --git a/src/gateway/server/preauth-connection-budget.ts b/src/gateway/server/preauth-connection-budget.ts
@@ -1,3 +1,4 @@
+// Pre-auth connection budget caps unauthenticated WebSocket handshakes per client IP before full gateway auth runs.
 import {
   parseStrictPositiveInteger,
   resolveIntegerOption,
diff --git a/src/gateway/server/presence-events.ts b/src/gateway/server/presence-events.ts
@@ -1,3 +1,4 @@
+// Presence event helpers broadcast system presence snapshots with synchronized gateway state versions.
 import { listSystemPresence } from "../../infra/system-presence.js";
 import type { GatewayBroadcastFn } from "../server-broadcast-types.js";
 
diff --git a/src/gateway/server/readiness.test.ts b/src/gateway/server/readiness.test.ts
@@ -1,3 +1,4 @@
+// Readiness checker tests cover startup grace, channel health, and stale socket decisions.
 import { describe, expect, it, vi } from "vitest";
 import type { ChannelId } from "../../channels/plugins/index.js";
 import type { ChannelAccountSnapshot } from "../../channels/plugins/types.js";
diff --git a/src/gateway/server/tls.ts b/src/gateway/server/tls.ts
@@ -1,3 +1,4 @@
+// Gateway TLS boundary loads listener certificate material from gateway config.
 import type { GatewayTlsConfig } from "../../config/types.gateway.js";
 import {
   type GatewayTlsRuntime,
diff --git a/src/gateway/server/ws-connection.test.ts b/src/gateway/server/ws-connection.test.ts
@@ -1,3 +1,4 @@
+// Gateway WebSocket connection tests cover handshake auth, shared sessions, and message-handler attachment.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ResolvedGatewayAuth } from "../auth.js";
 import {
diff --git a/src/gateway/server/ws-connection.ts b/src/gateway/server/ws-connection.ts
@@ -1,3 +1,4 @@
+// Gateway WebSocket connection handler owns pre-auth limits, handshake auth, presence, and message-handler attachment.
 import { randomUUID } from "node:crypto";
 import type { Socket } from "node:net";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
diff --git a/src/gateway/server/ws-shared-generation.ts b/src/gateway/server/ws-shared-generation.ts
@@ -1,3 +1,4 @@
+// WebSocket shared-session generation hashes gateway auth inputs so clients can detect credential rotation.
 import { createHash } from "node:crypto";
 import type { GatewayTrustedProxyConfig } from "../../config/types.gateway.js";
 import type { ResolvedGatewayAuth } from "../auth.js";
diff --git a/src/gateway/server/ws-types.ts b/src/gateway/server/ws-types.ts
@@ -1,3 +1,4 @@
+// Gateway WebSocket client types describe authenticated client state retained by the server.
 import type { WebSocket } from "ws";
 import type { ConnectParams } from "../../../packages/gateway-protocol/src/index.js";
 import type { PluginNodeCapabilityClient } from "../plugin-node-capability.js";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Close reason helpers keep WebSocket handshake failure text within RFC byte limits.`
`1`	`2`	`import { Buffer } from "node:buffer";`
`2`	`3`
`3`	`4`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Event-loop health tests cover delay, CPU, and utilization degradation classification.`
`1`	`2`	`import type { monitorEventLoopDelay, performance } from "node:perf_hooks";`
`2`	`3`	`import { describe, expect, it, vi } from "vitest";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Event-loop health monitor samples delay, utilization, and CPU pressure for gateway readiness snapshots.`
`1`	`2`	`import { monitorEventLoopDelay, performance } from "node:perf_hooks";`
`2`	`3`
`3`	`4`	`const EVENT_LOOP_MONITOR_RESOLUTION_MS = 20;`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Health-state tests cover probe coalescing, sensitive snapshots, and broadcast version behavior.`
`1`	`2`	`import { beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import type { HealthSummary } from "../../commands/health.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Gateway health state builds snapshots, caches health probes, and broadcasts health/presence version changes.`
`1`	`2`	`import type { Snapshot } from "../../../packages/gateway-protocol/src/index.js";`
`2`	`3`	`import { resolveDefaultAgentId } from "../../agents/agent-scope.js";`
`3`	`4`	`import { getHealthSnapshot, type HealthSummary } from "../../commands/health.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Hook client-IP config adapts gateway trusted-proxy settings for hook request handling.`
`1`	`2`	`import type { OpenClawConfig } from "../../config/types.openclaw.js";`
`2`	`3`	`import type { HookClientIpConfig } from "./hooks-request-handler.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Hook request handler validates hook tokens, applies mappings, dedupes requests, and dispatches wake or agent work.`
`1`	`2`	`import { createHash } from "node:crypto";`
`2`	`3`	`import type { IncomingMessage, ServerResponse } from "node:http";`
`3`	`4`	`import type { createSubsystemLogger } from "../../logging/subsystem.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Gateway hook server wiring translates external hook requests into wake events or isolated agent runs.`
`1`	`2`	`import { randomUUID } from "node:crypto";`
`2`	`3`	`import {`
`3`	`4`	`resolveDateTimestampMs,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Gateway HTTP listener tests cover retry behavior for lock contention and listen failures.`
`1`	`2`	`import { EventEmitter } from "node:events";`
`2`	`3`	`import type { Server as HttpServer } from "node:http";`
`3`	`4`	`import { describe, expect, it, vi } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Plugin node capability auth lets node-issued route capabilities supplement normal bearer gateway auth.`
`1`	`2`	`import type { IncomingMessage } from "node:http";`
`2`	`3`	`import type { AuthRateLimiter } from "../auth-rate-limit.js";`
`3`	`4`	`import {`