Skip to content

architecture-startup-refactor.md

Latest commit

 

History

History
74 lines (61 loc) · 3.91 KB

architecture-startup-refactor.md

File metadata and controls

74 lines (61 loc) · 3.91 KB

Gateway Startup Refactor

Summary

The gateway startup path is now split into three layers:

  1. Bootstrap/

    • Loads config overrides.
    • Binds the canonical GatewayConfig.
    • Applies environment overrides and explicit secret resolution.
    • Resolves GatewayRuntimeState.
    • Handles early exits for --health-check and --doctor.
    • Handles interactive --quickstart and pre-listener startup recovery for local terminal launches.
    • Enforces non-loopback auth-token requirements and public-bind hardening.

  2. Composition/ and Profiles/

    • Registers pre-build services in grouped extension methods.
    • Preserves the existing Core/Agent runtime model as the single source of truth for AOT vs JIT.
    • Builds runtime-only objects after builder.Build() in InitializeOpenClawRuntimeAsync(...).
    • Runtime assembly is now staged as:
      • strict public-bind preset application
      • service resolution
      • channel/webhook composition
      • built-in provider and tool registration
      • plugin loading and composition
      • agent runtime creation
      • skill watcher and automation refresh
      • final GatewayAppRuntime construction
      • profile hook and integration startup
    • Keeps plugin loading, provider registration, skill loading, hooks, and worker startup order intact.

  3. Pipeline/ and Endpoints/

    • Applies forwarded headers, CORS, WebSockets, worker startup, channel startup, and async shutdown coordination.
    • Prints the terminal-ready startup banner, startup notices, and post-ready local save/browser prompts.
    • Maps all HTTP/WebSocket routes outside Program.cs.

AOT vs JIT

Runtime mode selection still comes from GatewayConfig.Runtime and RuntimeModeResolver.

  • auto resolves to jit when dynamic code is supported and aot otherwise.
  • aot keeps the trim-safe, mainstream bridge lane.
  • jit keeps the expanded compatibility lane, including native dynamic plugins.

The gateway profile layer does not replace plugin/runtime capability enforcement. Existing fail-fast blocking and /doctor diagnostics still come from the core runtime/plugin subsystems.

Where Things Moved

  • Program.cs
    • now orchestrates bootstrap, quickstart/recovery selection, service registration, runtime initialization, pipeline mapping, endpoint mapping, and Run(...)
  • Bootstrap/GatewayBootstrapExtensions.cs
    • config loading, validation, runtime-state resolution, and early exits
  • Composition/*
    • grouped DI registration and post-build runtime assembly
  • Composition/RuntimeInitializationExtensions*.cs
    • thin orchestration plus extracted runtime composition and factory stages
  • Profiles/*
    • thin gateway composition hooks keyed off the already-resolved effective runtime mode
  • Pipeline/PipelineExtensions.cs
    • middleware, channel startup, workers, and shutdown wiring
  • Pipeline/GatewayRuntimeShutdownCoordinator.cs
    • owns ordered async cleanup for runtime-created resources and integrations
  • Endpoints/*
    • grouped route mapping by diagnostics, OpenAI surface, UI/control, WebSocket, and webhook boundaries
    • large admin and OpenAI surfaces are further decomposed into thin mappers plus domain-specific partial files

Adding New Startup Behavior

  • Add config/bootstrap rules in Bootstrap/ when behavior must happen before builder.Build().
  • Add DI-friendly services in the appropriate Composition/*ServicesExtensions.cs file.
  • Add runtime-only initialization in the relevant InitializeOpenClawRuntimeAsync(...) stage helper if it depends on built services, app lifetime, plugin loading, or runtime ordering.
  • Register runtime-owned cleanup with the shutdown coordinator instead of blocking synchronous lifetime callbacks.
  • Add new route handlers in the relevant Endpoints/* module and register them through MapOpenClawEndpoints(...).
  • Add profile-specific gateway composition only in Profiles/*; do not duplicate runtime-mode or plugin capability policy there.