docs: document gateway runtime startup

steipete · steipete · commit dc23e924efce · 2026-06-04T17:26:02.000-04:00
diff --git a/src/gateway/server-plugin-bootstrap.ts b/src/gateway/server-plugin-bootstrap.ts
@@ -1,3 +1,5 @@
+// Gateway plugin bootstrap helpers.
+// Applies activation config, installs runtime bindings, loads and pins plugins.
 import { primeConfiguredBindingRegistry } from "../channels/plugins/binding-registry.js";
 import { applyPluginAutoEnable } from "../config/plugin-auto-enable.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/gateway/server-runtime-config.ts b/src/gateway/server-runtime-config.ts
@@ -1,3 +1,5 @@
+// Gateway startup runtime-config resolver.
+// Normalizes bind/auth/HTTP/Tailscale/hook settings before server construction.
 import type {
   GatewayAuthConfig,
   GatewayBindMode,
diff --git a/src/gateway/server-runtime-handles.ts b/src/gateway/server-runtime-handles.ts
@@ -1,3 +1,5 @@
+// Gateway mutable runtime handles.
+// Provides stop-safe defaults for timers, sidecars, subscriptions, and services.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { HeartbeatRunner } from "../infra/heartbeat-runner.js";
 import type { ChannelHealthMonitor } from "./channel-health-monitor.js";
@@ -37,6 +39,8 @@ export type GatewayServerMutableState = {
 /** Creates gateway mutable state with inert handles that are safe to stop before startup finishes. */
 export function createGatewayServerMutableState(): GatewayServerMutableState {
   const noopInterval = () => {
+    // Dummy unref'd timers give shutdown code a concrete handle to clear even
+    // when startup exits before real maintenance intervals are installed.
     const timer = setInterval(() => {}, 1 << 30);
     timer.unref?.();
     return timer;
diff --git a/src/gateway/server-runtime-services.ts b/src/gateway/server-runtime-services.ts
@@ -1,3 +1,5 @@
+// Gateway post-ready runtime services.
+// Starts delayed maintenance, cron, heartbeat, recovery, and pricing refresh work.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { isVitestRuntimeEnv } from "../infra/env.js";
 import { startHeartbeatRunner, type HeartbeatRunner } from "../infra/heartbeat-runner.js";
@@ -35,6 +37,8 @@ function clearGatewayMaintenanceHandles(maintenance: GatewayMaintenanceHandles |
   if (!maintenance) {
     return;
   }
+  // Maintenance startup can race shutdown. Clear every interval handle here so
+  // callers can discard partially-created maintenance safely.
   clearInterval(maintenance.tickInterval);
   clearInterval(maintenance.healthInterval);
   clearInterval(maintenance.dedupeCleanup);
diff --git a/src/gateway/server-runtime-startup-services.ts b/src/gateway/server-runtime-startup-services.ts
@@ -1,3 +1,5 @@
+// Gateway startup-time runtime services.
+// Starts mode-dependent background monitors with inert handles for disabled paths.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ChannelHealthMonitor } from "./channel-health-monitor.js";
 import { startChannelHealthMonitor } from "./channel-health-monitor.js";
diff --git a/src/gateway/server-runtime-state.ts b/src/gateway/server-runtime-state.ts
@@ -1,3 +1,5 @@
+// Gateway HTTP/WebSocket runtime state factory.
+// Builds one server runtime with pinned plugin registries and lazy route handlers.
 import type { IncomingMessage, Server as HttpServer, ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
 import { WebSocketServer } from "ws";
diff --git a/src/gateway/server-startup-early.ts b/src/gateway/server-startup-early.ts
@@ -1,3 +1,5 @@
+// Gateway early-startup runtime helpers.
+// Starts discovery, remote skills, task maintenance, and delayed maintenance setup.
 import type { GatewayTailscaleMode } from "../config/types.gateway.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveCronJobsStorePath } from "../cron/store.js";
diff --git a/src/gateway/server-startup-post-attach.ts b/src/gateway/server-startup-post-attach.ts
@@ -1,3 +1,5 @@
+// Gateway post-attach startup sidecars.
+// Schedules warmups, sentinels, update checks, memory backend, and plugin services.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway plugin bootstrap helpers.`
	`2`	`+// Applies activation config, installs runtime bindings, loads and pins plugins.`
`1`	`3`	`import { primeConfiguredBindingRegistry } from "../channels/plugins/binding-registry.js";`
`2`	`4`	`import { applyPluginAutoEnable } from "../config/plugin-auto-enable.js";`
`3`	`5`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway startup runtime-config resolver.`
	`2`	`+// Normalizes bind/auth/HTTP/Tailscale/hook settings before server construction.`
`1`	`3`	`import type {`
`2`	`4`	`GatewayAuthConfig,`
`3`	`5`	`GatewayBindMode,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway startup-time runtime services.`
	`2`	`+// Starts mode-dependent background monitors with inert handles for disabled paths.`
`1`	`3`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`2`	`4`	`import type { ChannelHealthMonitor } from "./channel-health-monitor.js";`
`3`	`5`	`import { startChannelHealthMonitor } from "./channel-health-monitor.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway HTTP/WebSocket runtime state factory.`
	`2`	`+// Builds one server runtime with pinned plugin registries and lazy route handlers.`
`1`	`3`	`import type { IncomingMessage, Server as HttpServer, ServerResponse } from "node:http";`
`2`	`4`	`import type { Duplex } from "node:stream";`
`3`	`5`	`import { WebSocketServer } from "ws";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway early-startup runtime helpers.`
	`2`	`+// Starts discovery, remote skills, task maintenance, and delayed maintenance setup.`
`1`	`3`	`import type { GatewayTailscaleMode } from "../config/types.gateway.js";`
`2`	`4`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`3`	`5`	`import { resolveCronJobsStorePath } from "../cron/store.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway post-attach startup sidecars.`
	`2`	`+// Schedules warmups, sentinels, update checks, memory backend, and plugin services.`
`1`	`3`	`import fs from "node:fs";`
`2`	`4`	`import os from "node:os";`
`3`	`5`	`import path from "node:path";`