docs: document gateway server runtime

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";
 
 /**

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 {

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;

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";
 

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";

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";
 

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";

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,

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";

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 {

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,

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";

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 {

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,

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";
 

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";

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,

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 {

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";

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";

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";