Web Server Launcher

Purpose

The Web Server Launcher subtopic addresses the need for a flexible and extensible web server infrastructure within the broader scope of the [REST API and Web Launchers](80564) topic. It provides a standardized mechanism to launch a web server that supports modular extensions called sublaunchers. This design enables the web server to host multiple web-based agent interaction endpoints, APIs, and UI components, each potentially implemented as a sublauncher.

Unlike fixed server implementations, the Web Server Launcher allows command-line driven configuration to selectively enable sublaunchers, facilitating customized web server behaviors tailored to different use cases. This modularity supports scalability and separation of concerns, where each sublauncher can independently manage routing, handlers, and startup behavior while coexisting within a single HTTP server process.

Functionality

Core Features

• Command-Line Parsing with Sublaunchers:
  The launcher parses command-line arguments to identify which sublaunchers to activate. Each sublauncher declares a unique keyword and is responsible for parsing its own command-line options. For example, a sublauncher might handle REST API endpoints or A2A protocol integration.

• Sublauncher Interface:
  The launcher defines a Sublauncher interface that each extension implements:

  • Keyword() string — unique identifier used on the command line.

  • Parse(args []string) ([]string, error) — parses sublauncher-specific flags.

  • SetupSubrouters(router *mux.Router, config *launcher.Config) error — adds HTTP routes and handlers.

  • UserMessage(webURL string, printer func(...any)) — outputs helpful startup messages.

  • CommandLineSyntax() and SimpleDescription() — provide CLI usage information.

• Router Composition:
  The launcher builds a base HTTP router using gorilla/mux and delegates route setup to each active sublauncher. This allows multiple web components (e.g., REST APIs, Web UI) to co-exist seamlessly.

• Server Configuration:
  Supports configurable server parameters such as port, read/write timeouts, and idle timeouts through command-line flags.

• Lifecycle Management:
  The launcher starts the HTTP server and manages graceful error handling and logging of server events, including the listing of active sublaunchers and their user messages on startup.

Command-Line Parsing Workflow

1. Parse flags specific to the web server launcher (e.g., --port, --read-timeout).

2. Parse remaining arguments to detect sublauncher keywords.

3. For each sublauncher keyword found, delegate parsing of its own arguments.

4. Validate that no unknown or duplicate keywords are present.

5. Return any unparsed arguments for further processing or error reporting.

HTTP Server Startup Workflow

• Create a base mux.Router.

• For each active sublauncher, invoke SetupSubrouters to add routes.

• Log startup details including port and accessible URLs.

• Start http.Server with configured timeouts and router handler.

• Log HTTP request details via middleware.

Code Interaction Highlights

• The webLauncher struct holds sublauncher instances and manages their activation:

type webLauncher struct {
  flags        *flag.FlagSet
  config       *webConfig
  sublaunchers []Sublauncher
  activeSublaunchers map[string]Sublauncher
}

• Command-line parsing ensures uniqueness of sublauncher keywords and delegates flag parsing:

func (w *webLauncher) Parse(args []string) ([]string, error) {
  // Map keywords to sublaunchers
  ...
  w.flags.Parse(args)
  ...
  for len(restArgs) > 0 {
    keyword := restArgs[0]
    sublauncher, ok := keyToSublauncher[keyword]
    restArgs, err = sublauncher.Parse(restArgs[1:])
    w.activeSublaunchers[keyword] = sublauncher
  }
  return restArgs, nil
}

• The HTTP server is started with configured timeouts and the composed router:

srv := http.Server{
  Addr:         fmt.Sprintf(":%v", w.config.port),
  WriteTimeout: w.config.writeTimeout,
  ReadTimeout:  w.config.readTimeout,
  IdleTimeout:  w.config.idleTimeout,
  Handler:      router,
}
err := srv.ListenAndServe()

Integration

The Web Server Launcher acts as the foundational component that ties various web-based interaction capabilities under one HTTP server. It complements the [REST API Controllers](/80564) which implement the HTTP handlers themselves and the [Router Setup](/80564) subtopic that defines the routing logic.

Sublaunchers such as the [API and A2A Sublaunchers](/80564) extend the launcher by adding REST API and Agent-to-Agent protocol endpoints, enabling distributed agent communication over HTTP/gRPC. The [Web UI Launcher](/80564) sublauncher adds embedded Angular-based UI serving capabilities.

By supporting these sublaunchers, the Web Server Launcher provides a unified entry point that can be flexibly configured for different deployment scenarios, including pure API servers, interactive web frontends, or hybrid modes.

The launcher also integrates with the [Session Management (80559)] and [Agent Execution Runner (80560)] indirectly by exposing HTTP endpoints that invoke agent workflows and manage session state through REST calls.

Diagram

flowchart TD
CLI[Command Line Input]
ParseWebFlags[Parse Web Flags]
IdentifySublaunchers[Identify Sublaunchers]
ParseSublauncherFlags[Parse Sublauncher Flags]
BuildRouter[Build Base Router]
SetupSubrouters[Setup Sublaunchers' Routes]
StartHTTPServer[Start HTTP Server]
HandleRequests[Handle HTTP Requests]
LogRequests[Log Requests]
CLI --> ParseWebFlags --> IdentifySublaunchers --> ParseSublauncherFlags
ParseSublauncherFlags --> BuildRouter --> SetupSubrouters --> StartHTTPServer
StartHTTPServer --> HandleRequests --> LogRequests --> HandleRequests

This flowchart illustrates the key process steps of the Web Server Launcher, from command-line parsing through sublauncher activation, HTTP router composition, to server startup and request handling.